home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
olrdrs
/
1st_111b.zip
/
ADVANCED.DOC
< prev
next >
Wrap
Text File
|
1993-05-23
|
179KB
|
4,929 lines
┌──────────────────────────────────────────────────────────────────┐
│ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ ▄██ │ │
│ │ ██ ▄▄▄▄▄▄ ▄▄▄▄▄▄ │ │
│ │ ██ ██▀▀▀▀ ▀▀██▀▀ │ │
│ │ ██ ▀▀▀▀██ ██ │ │
│ │ ██ ██████ ██ │ │
│ │ │ │
│ │ 1stReader for DOS │ │
│ │ The Advanced User's Guide │ │
│ │ │ │
│ │ │ │
│ │ Entire work │ │
│ │ Copyright 1993 by Mark Herring │ │
│ │ All Rights Reserved │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ │ Sparkware │ │
│ │ Post Office Box 386 │ │
│ │ Hendersonville, Tennessee 37077 │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ │
└──────────────────────────────────────────────────────────────────┘
NOTICE
EXCEPT FOR THE EXPRESS WARRANTY SET FORTH ABOVE, SPARKWARE
GRANTS NO OTHER WARRANTIES, EXPRESSED OR IMPLIED, BY STATUE
OR OTHERWISE, REGARDING THE DISK, PROGRAMS AND RELATED
MATERIALS, THEIR FITNESS FOR ANY PURPOSE, THEIR QUALITY,
THEIR MERCHANTABILITY, OR OTHERWISE.
THE LIABILITY OF SPARKWARE UNDER THE WARRANTY SET FORTH
ABOVE SHALL BE LIMITED TO THE AMOUNT PAID BY THE CUSTOMER
FOR THE PRODUCT. IN NO EVENT SHALL SPARKWARE BE LIABLE FOR
ANY SPECIAL, CONSEQUENTIAL, OR OTHER DAMAGES FOR BREACH OF
WARRANTY.
SPARKWARE RESERVES THE RIGHT TO MAKE ANY CHANGES TO THESE
PROGRAMS, DOCUMENTATION AND CUSTOMER SUPPORT PLANS AT ANY
TIME WITHOUT PRIOR NOTICE.
THIS SOFTWARE PROGRAM IS A PROPRIETY PRODUCT OF SPARKWARE
AND IS PROTECTED BY COPYRIGHTS AND INTERNATIONAL TREATIES.
YOU MUST TREAT THIS SOFTWARE LIKE ANY OTHER COPYRIGHTED
MATERIAL, EXCEPT THAT YOU MAY MAKE AN ARCHIVAL COPY OF THE
SOFTWARE FOR EACH COPY THAT IS LICENSED TO YOU. YOU MAY
DISTRIBUTE THE SOFTWARE TO OTHERS SO LONG AS (A) THE
1ST.KEY OR QMAIL4.KEY FILE IS NOT DISTRIBUTED, (B) THE
SOFTWARE IS DISTRIBUTED UNMODIFIED. YOU MAY NOT DECOMPILE,
DISASSEMBLE, REVERSE ENGINEER, COPY, TRANSFER, OR OTHERWISE
USE OR MODIFY THIS SOFTWARE EXCEPT AS STATED HEREIN.
SPARKWARE GRANTS YOU THE RIGHT TO USE THIS SOFTWARE FOR
TRIAL PERIOD NOT TO EXCEED THIRTY (30) DAYS. USE AFTER
THIRTY DAYS REQUIRES REGISTRATION AS DOCUMENTED IN THIS
MANUAL.
1stReader
Entire work Copyright 1993 by Mark Herring
All Rights Reserved
Sparkware
Post Office Box 386
Hendersonville, Tennessee 37077-0386
(615) 230-8822 24 hour support bulletin board system
(615) 230-MAIL Office (10-12, 1-5 central time weekdays)
TABLE OF CONTENTS
DOS command line switches................................ 3
/CALL............................................ 3
/DAY............................................. 3
/DEBUG........................................... 3
/MAXLINES........................................ 4
/MPU401.......................................... 5
/NON............................................. 5
/NOSCAN.......................................... 5
/ONLYREPS........................................ 5
/QWK............................................. 6
/REP............................................. 6
/SETUP........................................... 6
/SHOWDEL......................................... 6
/SILENT.......................................... 7
/SLOW............................................ 7
/SWAP............................................ 7
/TIME............................................ 7
/XON............................................. 8
Creating 1stReader LOAD files............................ 9
1stReader Support Files.................................. 10
.BAT (or .BTM) files............................. 11
$$MAIL.BAT....................................... 11
$$REPLY.BAT...................................... 12
$$CALL.BAT....................................... 12
$$CHECK.BAT...................................... 12
$$TERM.BAT....................................... 12
$$BATCH.BAT...................................... 13
$$START.BAT and $$END.BAT........................ 13
$$REPLIES.BAT.................................... 13
$$FILER.BAT...................................... 13
$$EXIT.BAT....................................... 13
$$SPELL.BAT...................................... 14
$$CNAMES.BAT..................................... 14
$$Fxx.BAT........................................ 14
$$SHELL.BAT...................................... 14
.CMD and .LST files.............................. 15
$$1ST.CMD........................................ 15
$$ppff.CMD....................................... 16
Multiple EDITORS and LIST programs....................... 16
SHELL modifiers.......................................... 17
/API............................................. 17
/CGA, /EGA and /VGA.............................. 18
/CLS and /NOCLS.................................. 18
/CURSOR_ON and /CURSOR_OFF....................... 18
/DISPLAY......................................... 18
/EXPORT.......................................... 19
/FONT............................................ 19
/IN.............................................. 19
/OUT............................................. 19
/LIST............................................ 20
/MACRO........................................... 20
/MSGTEXT......................................... 20
/NS and /SS...................................... 21
/NULL and /NONULL................................ 21
/PAUSE........................................... 21
/SCRNSAVE........................................ 21
KEYBOARD.$$$..................................... 21
MESSAGE.$$$...................................... 22
LIST.$$$......................................... 22
<confname>.TMP files............................. 22
.CMD controls.................................... 23
Features................................................. 23
FEATURE=CALL..................................... 23
FEATURE=MAIL..................................... 23
FEATURE=MANAGER.................................. 24
FEATURE=SETUP.................................... 24
FEATURE=SNAPSHOT................................. 24
FEATURE=TAGLINES................................. 24
FEATURE=TERMINAL................................. 24
MultiMedia Extensions (MME).............................. 25
.MME files....................................... 26
Special files.................................... 27
$$ALARM.......................................... 27
$$CHKPRT......................................... 27
$$EXIT........................................... 27
$$H-<help_recnum>................................ 27
$$HELP........................................... 27
$$INTRO.......................................... 27
\1ST\BBS\<confnum>............................... 27
NEWS............................................. 28
NEWFILES......................................... 28
SERVICES......................................... 28
LEAVING.......................................... 28
$$TRANS.......................................... 28
The 1stReader Applications Program Interface (API)....... 29
1stReader Integer API table...................... 29
1stReader Long Integer API table................. 34
1stReader String API table....................... 35
@Variables supported by 1stReader................ 38
1stReader script language................................ 40
ABORT............................................ 40
API.............................................. 40
AUTOEXIT......................................... 40
BREAK............................................ 41
CALL............................................. 41
CAPTURE.......................................... 41
CHECKTIME........................................ 41
CLS.............................................. 41
COMMENT.......................................... 41
COUNT............................................ 41
DEBUG............................................ 42
DISCONNECT....................................... 42
DOWNLOAD......................................... 42
EDIT............................................. 42
EXIT............................................. 42
FLAG............................................. 43
FOUND=........................................... 43
GOSUB............................................ 43
GOTO............................................. 43
HANGUP........................................... 43
HELP............................................. 43
IF............................................... 44
KEYSTROKE=....................................... 44
KILL............................................. 44
LIST............................................. 44
LOCATE........................................... 44
LOCKLINE......................................... 45
LOOKFOR.......................................... 45
MME.............................................. 45
NEWFILES......................................... 45
NEW_PASSWORD..................................... 46
PAUSE............................................ 46
PLAY............................................. 46
PROMPT........................................... 46
REQ_FILE......................................... 46
REQ_SETFILE...................................... 46
REQ_NEXT......................................... 46
REQ_DONE......................................... 47
REQ_CONF......................................... 47
REQ_SET.......................................... 47
REPLIES.......................................... 47
RETURN........................................... 47
RUN.............................................. 47
SET_FLAG......................................... 47
SET_PASSWORD..................................... 48
SHOW............................................. 48
SWITCH........................................... 48
TERMINAL......................................... 49
TERSE............................................ 49
TRANSMIT......................................... 49
TRANSMIT......................................... 49
TIMEOUT.......................................... 50
UPLOAD........................................... 50
WAITFOR.......................................... 50
WEEKDAY.......................................... 50
Special @variables............................... 51
Special characters............................... 52
Hints and Tips........................................... 53
Support for .BIN and .B1N files.................. 53
The WELCOME file................................. 53
Using KEYBOARD.$$$ from the internal editor...... 54
Pre-Print and Post-Print strings................. 54
Printer definition............................... 54
Create your OWN help files....................... 54
1stReader is network ready....................... 55
GO.ASC, GO.ANS, GO.BIN, GO.B1N................... 55
Automatic DOORWAY ON and DOORWAY OFF modes....... 56
"Header" files................................... 56
Auto sensing dialog boxes........................ 57
"Ok" and "Cancel" buttons........................ 57
Attention John Hancock fans!..................... 57
Specialized conference files..................... 58
Support for DOOR.ID.............................. 58
Downloading files................................ 58
Longer signatures................................ 58
Multiple signatures.............................. 59
Support for the "1ST" file....................... 59
Automatic SuperShell............................. 59
Nonstandard serial ports......................... 60
New commands supported in DOOR.ID................ 60
LIST is restricted............................... 60
Robocomm-named packets supported................. 61
QMAIL4 is assumed................................ 61
Three button mice users.......................... 61
Using SPACE BAR and SHIFT+ENTER.................. 61
Protect those 'questionable' taglines............ 62
'Hotkey' your .CMD and .LST entries.............. 62
Entry fields are accessible...................... 62
Sysops can use Qmail Door in DOS using 1stReader. 63
Control characters in .LST files and KEYBOARD.$$$ 63
$$DIAL.SCR supported............................. 64
Addition bulletin board systems supported........ 64
Carriage returns in the modem init string........ 64
SERVICES.NEW..................................... 64
Clear all entry fields with one keystroke........ 65
QSZ supports 'crash-recovery'.................... 65
Assign different prefixes to telephone numbers... 65
Access interrupts from DOS command line functions 66
NAPLPS support is now available.................. 67
Make temporary changes to your 1stReader setup... 67
Tagline support from the terminal section........ 67
The 'CONFIRMATION' field......................... 68
The .COPY command................................ 68
1stReader automatically aborts a script.......... 68
Picklist notices................................. 68
Scroll quickly through large messages............ 69
Restricting some .CMD functions.................. 69
Locate a file inside your system's PATH statement 69
Move files automatically into the BBS directory.. 69
Disconnect immediately after an upload/download.. 70
Modify the 1stReader API after a DOS shell....... 70
Usenet message headers........................... 70
Alias signatures................................. 71
The virtual keyboard............................. 71
The EXTRA FEATURE button......................... 71
Display files directly from a .CMD file.......... 72
'$<macro>' now available in ANSI files........... 72
Sensing color attributes......................... 73
The NEWS.LST file................................ 73
The ATTACHED.LST file............................ 73
Save some disk space............................. 73
The INSTALL module............................... 74
Creating offline help for bulletin boards........ 74
Please Note
-----------
Except for the express warranty set forth, Sparkware grants
no other warranties, expressed or implied, by statue or
otherwise, regarding the disk, programs and related
materials, their fitness for any purpose, their quality,
their merchantability, or otherwise.
The liability of Sparkware under the warranty set forth above
shall be limited to the amount paid by the customer for the
product. In no event shall Sparkware be liable for any
special, consequential, or other damages for breach of
warranty.
Sparkware reserves the right to make any changes to these
programs, documentation and customer support plans at any
time without prior notice.
This software program is a propriety product of Sparkware and
is protected by copyrights and international treaties. You
must treat this software like any other copyrighted material,
except that you may make an archival copy of the software for
each copy that is licensed to you. You may distribute the
software to others so long as:
A) The 1ST.KEY or QMAIL4.KEY file(s) is not
distributed.
B) The software is distributed unmodified.
You may not decompile, disassemble, reverse engineer, copy,
transfer or otherwise use or modify this software except as
stated herein.
Sparkware grants you the right to use this software for a
trial period not to exceed THIRTY (30) days. Use after
thirty days requires registration.
Qmail 1stReader
Entire work Copyright 1993 by Mark Herring
All Rights Reserved
Sparkware
Post Office Box 386
Hendersonville, Tennessee 37077-0386
(615) 230-8822 24 hour support bulletin board system
(615) 230-MAIL Office (10-12, 1-5 central time weekdays)
Page 1
This manual is designed to help the advanced 1stReader access
all of the features found in the 1stReader offline mail
system. If you are new to 1stReader or offline mail readers
in general, we strongly recommend that you do not use this
guide until you are familiar with 1stReader.
1stReader was designed to be easily understood by the novice
user. However, there are plenty of features available for
the advanced power user "under the hood". The design
philosophy behind the 1stReader system was to provide an
interface for novice users that they could easily understand
and use. The power user features are hidden underneath this
interface and you have the ability to access them.
Remember, you do NOT need this guide in order to use
1stReader. However, you can change the way 1stReader
operates by following the tips and suggestions in this guide.
Page 2
DOS command line switches
-------------------------
1stReader supports a number of DOS command line switches you
can use at startup. These switches, when placed after the
DOS command 1ST.EXE, allow you to change how 1stReader is
configured and operates. You can 'stack' as many command
line switches as you wish. You can also create files that
contain the DOS command line switches that can be easily
loaded.
/CALL: <list of systems>
-----------------------.
Tells 1stReader to immediately begin calling <list of
systems> from the DOS command prompt. This switch lets you
call bulletin board systems directly from a batch file
instead of navigating through the 1stReader user interface.
Example: 1ST /CALL: SPARKY EXECNET CHANNEL1
/DAY: <days to call>
--------------------
The DAY switch lets you tell 1stReader which days of the week
to call a bulletin board system. This switch is designed for
users who want 1stReader call and receive new messages from
inside a batch file that runs nightly on your system. Great
for sysops who use 1stReader to make their nightly mail runs.
The days of the week are represented by numbers. Sunday=1,
Monday=2, Tuesday=3, Wednesday=4, Thursday=5, Friday=6 and
Saturday=7. This example shows how to setup 1stReader so it
will only call these systems on Sunday, Tuesday and Thursday:
Example: 1ST /DAY: 135 /CALL: system1 system2 system3
/DEBUG
------
This command line switch will create various 'debugging'
files that can tell you how 1stReader is operating.
Depending on what you are doing within the reader, up to
three debugging files can be created in your 1stReader system
subdirectory. These files are:
Page 3
1ST.DBG
This file contains information about your system and
how it was operating while executing 1stReader. It
will contain the following data on each line in the
file:
Free RAM available
Free string space available
Free stack space available
Next file handle number to allocate
Time of execution
Description of operation
SCRIPTS.DBG
This file contains a capture of the scripts executed
by 1stReader when you call a bulletin board system.
All @variables will be translated in this file so it
provides an accurate record of how scripts were
executed by 1stReader.
SERIAL.DBG
This file contains characters received by 1stReader
from your modem when calling a bulletin board system.
/MAXLINES: <maximum number of lines per message>
------------------------------------------------
The internal editor inside 1stReader lets you create replies
of up to 200 lines each. If you decide to use an external
editor then the size of your replies can be as large as you
wish.
1stReader 'breaks' your replies at 99 lines per message.
This is due to the limits imposed by some bulletin board
software and older offline mail readers still in use today.
However, you can adjust the size of the reply by using the
/MAXLINES command line switch.
Example: 1ST /MAXLINES: 200
This command would cause 1stReader to break long replies at
every 200 lines. If you wish to break a long message at the
end of a paragraph you can insert ".PG" after the line you
wish to break. ".PG" is not included in your reply when
transmitted to the bulletin board system.
Page 4
/MPU401
-------
If you have a MPU401-compatible MIDI device connected to your
computer then this command will make 1stReader output .MID
files to your MIDI device rather than using a sound card.
Note that your MIDI interface must be connected to port 330h.
/NON
----
1stReader uses "RTS" checking to determine when your modem is
ready to send characters to the remote system. You can
disable ALL checking by using the /NON switch.
Example: 1ST /NON
/NOSCAN
-------
If you have turned on the multimedia switch inside 1stReader
then anytime you display a text file the reader will try to
locate a .MME, .MID, .CMF or .VOC file that matches the
filename being displayed. The "/NOSCAN" switch stops
1stReader from scanning for these sound files when displaying
text files.
/ONLYREPS: <list of systems>
----------------------------
This DOS command line switch works just like the /CALL:
switch except that it will only call systems in the <list of
systems> that have message replies waiting to transmit.
Example: 1ST /ONLYREPS: SPARKY EXECNET CHANNEL1
If the mail sites SPARKY and CHANNEL1 have replies waiting to
be transmitted back to these systems, 1stReader will call
these systems. If EXECNET does not have replies waiting to
be transmitted then the reader will skip calling EXECNET.
Page 5
/QWK: <file extension>
----------------------
Since 1stReader is designed to work with QWK formatted mail
packets, by default it looks for mail packets using the "Q*"
file extension. You can override this extension by using the
/QWK command line switch.
Example: 1ST /QWK: OPX
Why would you want to change the file extension? Later in
this guide we cover two batch files named "$$INTRO.BAT" and
"$$EXIT.BAT". Programmers can use these files to create
programs that convert other non-QWK mail packets to and from
the QWK format. The /QWK command line switch lets them tell
1stReader which type of mail packet to scan for in the list
of packets
on file.
/REP: <file extension>
----------------------
This command line switch works just like the /QWK switch
except that it lets you change the default extension for mail
reply packets. "REP" is the extension used for QWK mail
packets, but by using this switch you can change the
extension to any value desired.
Example: 1ST /REP: TMP
/SETUP: <filespec>
------------------
You can load a different 1stReader setup file (.SET) from the
DOS command line using this switch.
Example: 1ST /SETUP: NETWORK.SET
/SHOWDEL
--------
If this command line switch is used then whenever you delete
a reply in 1stReader the message will remain in the REPLIES
conference until you close the mail packet. Normally, when
you delete a reply in the REPLIES conference, 1stReader will
immediately remove it from the list of replies. This switch
keeps the message in the REPLIES conference so you can
undelete it later in the same session.
Example: 1ST /SHOWDEL
Page 6
/SILENT
-------
Sometimes it might be nice if you could turn off the noises
and beeps 1stReader makes. You could either be at the office
or doing a late night mail run at 3:00 am. In either case,
use this command line switch to make 1stReader totally
silent - no matter how you have configured the reader.
Example: 1ST /SILENT
/SLOW: <milliseconds>
---------------------
1stReader pauses five milliseconds for each ANSI position
statement it receives while displaying color files and
messages. If you have a faster computer this pause might not
be long enough. You can use this DOS command line switch to
vary the number of milliseconds to pause.
Example: 1ST /SLOW: 15
/SWAP: <filespec>
-----------------
1stReader's SuperShell system swaps the memory being used
into either EMS memory (if enough is available) or to a disk
file. Normally, this disk file is named $$1ST.RAM and is
located in your 1stReader system subdirectory. If you use
this command line switch then you can point 1stReader to
another filename if you wish. If you have a large RAM disk
available it would be nice to point the swap file into the
RAM disk for faster speed. 1stReader overwrites <filespec>.
/TIME: <military format>
------------------------
This command line switch works with the /CALL and /ONLYREPS
switches so you can set the time you wish to start calling
the <list of systems>. Remember, you MUST use military
format if you wish to call systems starting after 12:59 pm
(1:00 pm is translated into 13:00 hours).
Examples:
1ST /CALL: SPARKY EXECNET CHANNEL1 /TIME: 20:00
1ST /ONLYREPS: SPARKY EXECNET CHANNEL 1 /TIME: 20:00
Page 7
/XON
----
1stReader uses the "RTS" method of checking to determine when
your modem is ready to receive characters. This switch is
just like the /NON switch except that instead of turning off
ALL forms of line checking, it forces 1stReader to use
XON/XOFF checking (required by older modems).
Example: 1ST /XON
Page 8
Creating 1stReader LOAD files
-----------------------------
You can create text files that contain multiple DOS command
line switches and easily load them from the DOS command
prompt with 1stReader. Simply use a text editor to create a
file (you may give it any name you wish) and then tell the
reader to load it from the DOS command prompt. 1stReader
will read the switches from the file just like you entered
them from the DOS command line prompt.
For example, if you wanted to create a LOAD file that would
always allocate 2,000 messages per conference and 10,000
lines per message (using EMS memory) and loads the
BIGSERF.FNT file, you could create a file named BIGEMS in a
text editor. The file would contain this entry:
/EMS: 2000:10000 /FONT: BIGSERIF.FNT
You could then tell 1stReader to load the BIGEMS file by
using the DOS command:
1ST @BIGEMS
The "@" tells 1stReader to look for the file "BIGEMS" and if
found use the DOS command line arguments it contains to start
up 1stReader. There is one special filename reserved for
this feature. If you create a file named "SWITCHES.1ST" and
you simply start 1stReader by typing "1ST" from the DOS
command line, then 1stReader will look for SWITCHES.1ST. If
SWITCHES.1ST is found then the reader will read it for the
DOS command line switches.
Page 9
1stReader Support Files
-----------------------
There are files you can place inside your 1stReader system
subdirectory that can help you change the way 1stReader
operates.
Before you continue, we need to explain the file directory
structure used by 1stReader. You can, of course, change this
layout in the SETUP section inside 1stReader, but by default
this subdirectory tree structure is used:
\1ST\ 1stReader system subdirectory
\1ST\SCRIPTS\ Script files location
\1ST\PACKETS\ Mail packets location
\1ST\FILES\ Files you download
\1ST\PROGRAMS\ Programs area
\1ST\FOLDERS\ Folders area
\1ST\MME\ Location of sound files
\1ST\WORK\ Temporary mail work area
\1ST\REP-WORK\ Temporary replies work area
\1ST\SERVICES\ Temporary services work area
\1ST\BBS\QWK-ID\ The BBS subdirectories
The two locations we are concerned about right now are the
System subdirectory (we'll call it SYSTEM) and the BBS
subdirectories (we'll call it BBS). The BBS subdirectories
are created underneath the \1ST\BBS area. Each system you
call with 1stReader has a unique BBS subdirectory underneath
this area. It is here that all bulletins, archived file
lists, script files and other items unique to each system is
stored. So, when we refer to the BBS subdirectory, we are
actually referring to the unique subdirectory for a
particular bulletin board system, not \1ST\BBS\ itself.
The files described below can be located in either the
SYSTEM, SCRIPTS or BBS subdirectory. 1stReader will always
look in the BBS subdirectory for the file first. If the file
is not found then 1stReader will check for the file in the
SCRIPTS subdirectory. Finally, if the file is not found in
that subdirectory the reader checks the SYSTEM subdirectory.
The major exception to this rule is when 1stReader is at the
OPENING SCREEN menu. Since you haven't selected a system
from the menu 1stReader will skip checking the BBS
subdirectory first.
If the file is found the BBS subdirectory then that file will
only work when you have selected that system from the opening
screen menu. Otherwise, if the file is not found in the BBS
subdirectory but it is found elsewhere that file is available
at ALL times.
Page 10
There are four different types of support file. They are
.BAT, .CMD, .LST and .MME files.
.BAT (or .BTM) files
--------------------
You can "by pass" the built-in features found in 1stReader
with your own personal favorites if you wish. Of course, you
can use your own internal file LIST or EDITOR programs by
entering their DOS commands in SETUP's EDITOR section. But
you can replace many of the internal systems found in
1stReader by using batch files.
1stReader will follow the normal BBS/SCRIPTS/SYSTEM search
method to locate these files unless specifically mentioned
in the descriptions below. Also, if you have turned on 4DOS
support within 1stReader remember that 1st will be looking
for .BTM files instead.
1stReader never actually executes the batch file you create.
Instead, it reads the contents of the batch file and creates
a temporary batch file to execute named $$EXEC.BAT. When
1stReader is reading the contents of your batch file it can
substitute values from the Applications Program Interface
(API). The API is defined later in this guide. All you need
to remember for now is that you can substitute API variables
in your batch files as needed.
$$MAIL.BAT
----------
If you wish to use your favorite telecommunications software
to call bulletin board systems you can replace the internal
module in 1stReader by creating a $$MAIL.BAT file. This file
passes along to the application the QWK-ID of the system you
have selected in the '%1' parameter in the batch file.
There are two communication systems that are designed to
transfer mail packets to and from offline mail systems.
These two programs are ICOM from Liberation Enterprises and
ROBOCOMM from Parsons Technologies. If you wish to use
either of these systems with 1stReader you need to create a
$$MAIL.BAT file that will CHDIR into the proper subdirectory
and then execute the program. Inside the batch file you need
to use these commands to run either program:
For ICOM use the command: ICOM /RUN:%1
For ROBOCOMM use the command: ROBOCOMM /A%1 /R
Page 11
The QWK-ID for the system is passed in the '%1' parameter so
you need to make sure you have a job (for ICOM) or an agenda
(for ROBOCOMM) prepared to call the bulletin board system.
$$REPLY.BAT
-----------
This batch file works just like $$MAIL.BAT except that it is
used if you wish to transmit replies back to the bulletin
board system without picking up new mail. If this batch file
is found and you have selected the "Get Mail" button and you
also have replies on file, you will be asked if you wish to
only transmit replies to the system.
$$CALL.BAT
----------
This batch file works just like $$MAIL.BAT except that it is
used to call the bulletin board and place the user in an
interactive terminal mode. You can interface 1stReader with
your favorite terminal program (ProComm, Telix, etc) by using
this batch file.
$$CHECK.BAT
-----------
This batch file lets 1stReader test archives for any
potential viruses that might be included in programs you
download from other bulletin board systems. Unfortunately,
it is a fact these days that people create programs that try
to destroy your data. In response to this threat, companies
have created programs to detect these virus programs before
they can infect your computer.
1stReader can automatically test for viruses by using the
$$CHECK.BAT batch file. Only one parameter is passed to this
batch file in the '%1' parameter, the location of the
subdirectory that contains the files to be tested.
$$CHECK.BAT should call your virus checking software passing
the location of this subdirectory to the program.
$$CHECK.BAT is automatically executed after you unpack an
archive downloaded from a bulletin board system.
$$TERM.BAT
----------
You can use your favorite telecommunications program with
1stReader. The $$TERM.BAT file can call a communications
program when you select the 'Terminal' button from the
'Opening Menu' screen. Simply use this batch file to call
your telecom program.
Page 12
$$BATCH.BAT
-----------
If you call more than one system in a batch mode (either by
using the /CALL, /ONLYREPS or by tagging multiple systems
from the list of systems, when finished calling these
systems, 1stReader will execute $$BATCH.BAT if the batch file
exists.
$$START.BAT and $$END.BAT
-------------------------
These batch files are executed automatically by 1stReader
when you begin and exit 1stReader. You can use these batch
files to perform any functions you wish.
$$REPLIES.BAT
-------------
This batch is executed by 1stReader as soon as a reply mail
packet is unbundled. The idea behind this batch file is to
allow you to process the reply mail packet in any way you
wish before you read the mail packet. The same parameters
used in the $$INTRO.BAT file are passed to this batch
file from 1stReader.
$$FILER.BAT
-----------
This batch file will execute whenever you click on the
"Files" button in the "Read messages" screen. It's designed
so you can process the NEWFILES.DAT file any way you wish.
The NEWFILES.DAT file contains a list of newly uploaded files
on a bulletin board system. Only one parameter is passed in
'%1' to the batch file, - the full name of the NEWFILES.DAT
filespec.
$$EXIT.BAT
----------
$$EXIT.BAT works just like $$INTRO.BAT, except that instead
of being a "preprocessor" for the mail packet it is a "post-
processor". This batch file is called after you have exited
the mail packet but before the contents of the work
subdirectories are erased. Any files found in the REP-WORK
subdirectory are included in the .REP reply mail packet.
Three parameters are passed to the $$EXIT.BAT file. These
parameters are:
%1 Name of the QWK-ID for the system
%2 Path to the work subdirectory
%3 Path to the replies subdirectory
Page 13
$$SPELL.BAT
-----------
If this batch file exists then 1stReader will ask you if you
wish to perform a spelling check on your reply just before
you save the message. The batch file uses the '%1' parameter
to store the filename being passed to the batch file. This
is a great way to interface spelling checkers like SHARESPELL
with 1stReader. Example (assumes ShareSpell is in the
\SSPELL subdirectory):
@ECHO OFF
CD \SSPELL
SS %1
$$CNAMES.BAT
------------
This batch file works when a user clicks on the "Conf List"
button in the 'Join a conference' screen. The idea behind
this batch is to allow 1stReader to shell to a program that
the user can query for conference information. Some systems
have over 5,000 conferences so a database isn't such a bad
idea!
$$Fxx.BAT
---------
These batch files (where 'xx' is a value from 1 to 10)
correspond to the function keys on your keyboard. If you
press the [SHIFT]+F10 key, for example, then 1stReader will
execute $$F10.BAT (if found). This feature lets you
interface programs that you wish to have executed from one
keystroke rather than inserting them into the [F7] command
files.
$$SHELL.BAT
-----------
Whenever you manage files 1stReader will take you into the
file manager. If you wish to use your own file managing
system create a file named $$SHELL.BAT. This batch file
should call your file manager. 1stReader passes the location
of the subdirectory to be managed in the '%1' parameter.
Page 14
.CMD and .LST files
-------------------
.CMD (Command) and .LST (pick list) files let you integrate
other programs into 1stReader. .CMD files are text files
that contain program descriptions and program commands in a
pulldown menu. You can call up the .CMD file(s) by pressing
the [F7] key on your keyboard.
.LST files let you pass on keyboard macros into 1stReader
using a pulldown menu too. Press the [F8] key on your
keyboard to call up .LST files. Please note that .LST files
are available for certain keyboard prompts only.
The format of a .CMD file is:
TITLE=<title description>
Description #1,DOS command #1
Description #2,DOS command #2
Description #3,DOS command #3
The format of a .LST file is:
TITLE=<title description>
Description #1,Keyboard macro #1
Description #2,Keyboard macro #2
Description #3,Keyboard macro #3
You may have up to 100 commands per file. You can also
"chain" other .CMD or .LST files by using the syntax:
Desc,FILE=filespec.CMD or Desc,FILE=filespec.LST
To create a .CMD file press ALT+F7. or press ALT+F8 to create
a .LST file. This will place you in the editor where you can
create the file. If you are in 'novice mode' then you will
know that a picklist is available because 1stReader displays
"[F8]=Picklist" on your screen.
$$1ST.CMD
---------
Usually, you will be interested in $$1ST.CMD. If this file
exists then 1stReader will load the file and display the menu
of functions in the middle of your screen. You can then
select which program you wish to execute and 1stReader will
SHELL and execute the DOS command.
Page 15
$$ppff.CMD
----------
Almost all of the keyboard input fields are identified in
1stReader by page and field number. If $$ppff.CMD exists
(where "pp" is the page number and "ff" is the field number)
then 1stReader will display THIS file instead of $$1ST.CMD,
if $$ppff.CMD exists. You can create custom .CMD files for
specific keyboard input fields by pressing the ALT+F7 key at
anytime.
Multiple EDITORS and LIST programs
----------------------------------
If you wish to use external editors or list programs you can
create EDITORS.CMD and LIST.CMD files that contain the
descriptions and commands needed to execute them. For
example, EDITORS.CMD might contain:
TITLE=External Editors
QEdit,Q %1 %2
TED,TED %1
DOS 6.00 Editor,EDIT %1
Instead of entering the DOS command for an editor you would
use the entry "EDITORS.CMD" instead. Then, when you are
about to SHELL to DOS to execute the external editor
1stReader will ask you to select an editor from this list.
'%1' gets translated into the ORIGINAL filespec and '%2' gets
translated into the REPLY filespec.
The same technique works for LIST.CMD except that you would
only use '%1' to be replaced by the name of the file to list.
1stReader supports up to 100 external editors and file
listers using this technique. You can create these files by
going into Setup's "EDITOR" section then entering LIST.CMD
and/or EDITORS.CMD in the appropriate entry field. Then
press ALT+F7 to create the file.
Page 16
SHELL modifiers
---------------
1stReader lets you control HOW it shells to a program using
"shell modifiers". These switches let you control whether
the current screen is saved or cleared before you shell to
DOS, if you wish to PAUSE before returning back to 1stReader,
etc.
Shell modifiers can be used in any DOS command executed from
within 1stReader. Usually, this means DOS commands issued
from .CMD menus. You can add SHELL modifiers directly into
batch files by adding this line into the batch file itself:
:1ST shell modifier1 shell modifer2 ...
/API: <filespec>
----------------
The /API modifier tells 1stReader to create a file named
<filespec> that contains the entire contents of the 1stReader
API (Applications Program Interface). This modifier lets
third-party programmers read the current environment used by
1stReader so they may take advantage of them for their
own programs.
The 1stReader API is defined later in this guide. Here is
the format for the file created by this modifier:
Version number INTEGER
Number of INTEGER API variables INTEGER (IMax)
Number of LONG API variables INTEGER (LMax)
Number of DEFAULT switches INTEGER (SwMax)
Number of STRING API variables INTEGER (SMax)
API(0)-API(IMax) INTEGER values INTEGER*(IMax+1)
API&(0)-API&(LMax) LONG values LONG*(LMax+1)
Switch(1)-Switch(SwMax) INTEGER*(SwMax)
Next comes the API$() lookup table. This is a table
that is SMax+1 entries long. Each API$() value has
an offset and length value in this table. Example:
API$(0) OFFSET:LENGTH
API$(1) OFFSET:LENGTH
You would read the offset to the variable you wish to
read and then SEEK to this position in the file and
read LENGTH number of bytes to access the string
variable.
Page 17
/CGA, /EGA and /VGA
-------------------
These modifiers are to be placed on DOS commands when the
shelled program requires that the system is connected to
either a CGA, EGA or VGA monitor.
For example, let's say you wanted to run a program that
displayed a GIF file. You can restrict use of the program to
systems that have VGA color monitors by using this command:
Display a GIF file,NANOGIF /VGA
A system equipped with a monochrome, CGA or EGA monitor would
not execute this command.
/CLS and /NOCLS
---------------
The /CLS modifier tells 1stReader to erase the screen and
display the DOS command before execution. /NOCLS tells
1stReader to leave the current screen intact and shell to the
program, providing a "seamless" screen. When the application
returns control back to 1stReader the current screen is
always restored.
/CURSOR_ON and /CURSOR_OFF
--------------------------
These two modifiers control the cursor while shelling from
1stReader. If you wish to turn the DOS cursor on while
shelling to a program use /CURSOR_ON. /CURSOR_OFF will turn
the cursor off. Note that 1stReader always restores the
cursor to the same condition after a DOS shell has taken
place.
/DISPLAY: <text>
----------------
This modifier can be used to display a dialog box while
shelling to a program from 1stReader. Any text following
this switch is displayed inside a dialog box on the screen as
1stReader shells to DOS.
Page 18
/EXPORT: <filespec>
-------------------
This modifier lets you export the current message into
<filespec> so you can shell to another program that reads
<filespec> for input. This is a powerful feature that lets
third-party software link into 1stReader and offer you
capabilities above those found in the reader.
The format of the exported message file is:
1stReader release number
Name of the bulletin board
Location
Telephone number
Sysop's name
Qmail Door serial number
PCBoard message status (225=Active, 226=Deleted)
Conference number
Message number
Message status flag
Date
Time
To
From
Subject
Reference number
Number of lines in text body
...Message text...
<filespec> is automatically deleted by 1stReader when you
return from the DOS command.
/FONT
-----
This modifier reloads a video font that was loaded by
1stReader using the /FONT: <filespec> DOS switch. Sometimes,
when you execute a program from within 1stReader, the program
can reset the video font. This modifier tells 1stReader to
reload the current font from disk after executing the DOS
command.
/IN: <filespec1> /OUT: <filespec2>
-----------------------------------
These two modifiers work together...there is no point in
using /IN without also using /OUT. They provide you with a
"flexible" API setup for third-party programmers.
This concept takes a bit of explaining. Remember the /API
modifier described earlier? That modifier creates a file of
every entry contained in the 1stReader API. As a third-party
programmer, you might only be interested in using a few of
the entries, but maybe not every single one.
Page 19
1stReader uses <filespec1> as a "template" in order to create
<filespec2>. The template can contain any information your
application requires in any order you wish. @variables
defined in <filespec1> are translated and written to
<filespec2>.
For example:
<filespec1> <filespec2>
----------------------- ------------------------
My App 1.01 My App 1.01
@API$(0) C:\1ST\1ST.SET
@API$(5) C:\1ST\
@API$(36),@DAY@ MARK HERRING,Wed
As you can see, 1stReader "reads" <filespec1> and translates
it into <filespec2>. Any "literals" that 1stReader cannot
translate get passed "as is". <filespec1> is never deleted
by 1stReader. <filespec2> is erased after returning from the
DOS command.
/LIST: <filespec>
After completing the DOS shell, 1stReader will look for
<filespec> and if found will list the file on the screen.
Unlike LIST.$$$, <filespec> is not deleted by 1stReader.
/MACRO: <text>
--------------
You can 'stuff' text into 1stReader's macro buffer
immediately after returning from a DOS command using this
modifier.
/MSGTEXT: <filespec>
--------------------
This modifier works just like /EXPORT except that <filespec>
only contains the text of the message and nothing else.
/EXPORT creates a file that includes the TO, FROM, SUBJECT
and other message header info.
/MSGTEXT will work great for those users who want to use
UUENCODE to rebuild an encoded file received via a Usenet
message, among many other uses.
Page 20
/NS and /SS
-----------
The /NS (No Supershell) modifier tells 1stReader that if
SuperShell has been turned ON by the user then it should not
invoke a SuperShell during this DOS command.
/SS (SuperShell) works in the opposite manner. It tells
1stReader to invoke SuperShell even if the user has not
turned SuperShell on.
/NULL and /NONULL
-----------------
"/NULL" tells 1stReader to add ">NUL" to the DOS command line
so that BIOS output will not echo to the screen. "/NONULL"
does the exact opposite - it will remove any ">NUL" added to
a DOS command. This lets you shell to programs that use BIOS
output and lets you see the output.
/PAUSE
------
This modifier tells 1stReader to pause and wait for a
keystroke before returning control back to the user.
/SCRNSAVE: <filespec>
---------------------
This modifier saves the current screen into <filespec> as a
BINARY file.
KEYBOARD.$$$
------------
This isn't a DOS command modifier but rather a file that can
contain information to be passed back to 1stReader. If you
shell to DOS from a keyboard input field, and the application
you execute creates a KEYBOARD.$$$ file in the current
subdirectory, this file is read by 1stReader and its contents
entered into the current keyboard entry field. This is an
excellent way for third-party applications (like address
books) to pass information back to 1stReader.
Page 21
MESSAGE.$$$
-----------
This too isn't a DOS command modifier. Instead, it is a file
that contains a full message that is to be saved by 1stReader
into the mail reply packet.
The idea behind supporting this file is to allow other
programs that might be shelled to from 1stReader to save
messages automatically, without having to go through the same
steps 1stReader performs to save the message.
Here is the format used for MESSAGE.$$$:
Line 1: Conference number to save message
Line 2: If a public message this line is
blank, otherwise the message is a
personal msg.
Line 3: Message TO field (address to whom)
Line 4: Message SUBJECT field
Line 5: Tagline to pass to 1stReader
Message text follows on line #6 and below.
1stReader always checks for MESSAGE.$$$ after a DOS shell and
deletes the file after saving the message.
LIST.$$$
1stReader will check for this file after a DOS shell. If the
file is found then LIST.$$$ will be displayed by 1stReader's
internal LIST module and then be deleted.
<confname>.TMP files
--------------------
The template files let you create 'forms' that are
automatically inserted into the editor when a user ENTERS a
new message. The form can be a standard bug report form or
any form you wish. The idea behind this feature is to give
the user an idea of what they should enter in a new message.
1stReader looks for <confname>.TMP using the current
conference's name (up to the first eight characters). For
example, if the user was in the 'TEST' conference and entered
a new message, 1stReader would look for TEST.TMP and if found
it would load it into the editor. If TEST.TMP is not found
then 1stReader looks for $$1ST.TMP instead.
If the internal editor is used 1stReader also toggles the
editor into an 'overstrike' mode.
Page 22
.CMD controls
-------------
Some programs that can be installed into a .CMD menu might
only operated after you have selected a bulletin board system
from the opening menu. They might not work properly because
the user might be located at the opening menu or in the
terminal mode. If you wish to prevent a program from
appearing in the menu when a BBS has not been selected, add
"<BBS>" to the DOS command for that option. This tells
1stReader to skip loading this command into the menu screen
if a BBS has not yet been selected.
Example:
Forward msg,FORWARD /IN:FORWARD.IN /OUT:FORWARD.$$$ <BBS>
Features
--------
You can also access some of the 1stReader internal routines
from a .CMD menu. In order to access the routines 1stReader
checks to make sure you are not already using the routines.
If you are using the routines then these commands will not
appear in your CMD menu at that time.
For example, if you are using the file manager and press the
[F7] to call up $$1ST.CMD and try to manage a subdirectory
from the list of commands, the FEATURE=MANAGER command will
not be displayed to you.
FEATURE=CALL
------------
Lets you call the currently selected bulletin board system
from the .CMD menu. 1stReader will place you in the terminal
mode and call the system logging you onto the BBS.
Example: Call this system,FEATURE=CALL
FEATURE=MAIL
------------
This feature works just like the CALL feature except that it
will make a full mail run to the selected bulletin board
system.
Example: Make a mail run,FEATURE=MAIL
Page 23
FEATURE=MANAGER directory [<ABS>]
---------------------------------
Lets you access the 1stReader file manager. If directory is
entered on the same line then 1stReader will manage
directory. If "<ABS>" is included on the command line then
the reader will not ask you for a directory path before
entering the file manager.
Example:
Manage Downloads,FEATURE=MANAGER @API$(2) <ABS>
FEATURE=SETUP
-------------
Lets you access the 1stReader setup section (the same section
used by the SETUP button on the Opening Menu).
Example: 1stReader setup,FEATURE=SETUP
FEATURE=SNAPSHOT <filespec>
---------------------------
This feature lets you capture the current screen into
<filespec> as a .BIN file. If you do not user a filespec
then 1ST-SNAP.BIN is used by default.
Example: Save screen,FEATURE=SNAPSHOT TEST.BIN
FEATURE=TAGLINES
----------------
You can manage your 1stReader taglines from anywhere within
1stReader using this feature.
Example: Manage taglines,FEATURE=TAGLINES
FEATURE=TERMINAL SCRIPT: filename PHONE: phone BAUD: baud
This feature lets you access the 1stReader terminal section.
If you have created a $$TERM.BAT file then the reader will
use this batch file to call up your terminal program
(1stReader will ignore the SCRIPT and PHONE parameters if
used).
You can also pass on to the terminal section the telephone
number of the system you wish to dial (and the baud rate to
use) as well as the name of a script file to execute.
Example:
Call Sparky's,FEATURE=TERMINAL PHONE: 230-8822 BAUD: 19200
Page 24
MultiMedia Extensions (MME)
---------------------------
If you have a Sound Blaster (or compatible) sound card
installed in your computer system then 1stReader can play
.VOC (sampled data), .CMF (FM music), .MID (midi) and .MME
files through your sound card. All you need to do is to turn
the "MultiMedia" switch ON in the SETUP/SWITCHES section
Please Note: It is not recommended that you turn on the
MultiMedia switch while running 1stReader under
Windows or Desqview.
If you do not have a sound card installed in
your computer or you do not wish to use MME
within 1stReader you should turn the multimedia
switch OFF.
If you start 1stReader using the /SILENT DOS
command switch then 1stReader will not play
multimedia files for that session.
Whenever you are in the 1stReader file manager you can select
a .VOC, .MID or .CMF file and 1stReader will play the file
through your sound card. However, when the reader displays a
text or ANSI file it will also look for a file that matches
the filename being displayed (but not the extension) and if
found, that file will be played through the sound card. It
is better to give an example of how this works...
Whenever you unpack a QWK mail packet in 1stReader the reader
always looks to display a WELCOME file included in the mail
packet. If you have MME turned on then 1stReader looks for
these files in the this order:
\1ST\BBS\<QWK-ID>\WELCOME.MME
\1ST\BBS\<QWK-ID>\WELCOME.MID
\1ST\BBS\<QWK-ID>\WELCOME.CMF
\1ST\BBS\<QWK-ID>\WELCOME.VOC
\1ST\MME\WELCOME.MME
\1ST\MME\WELCOME.MID
\1ST\MME\WELCOME.CMF
\1ST\MME\WELCOME.VOC
\1ST\WELCOME.MME
\1ST\WELCOME.MID
\1ST\WELCOME.CMF
\1ST\WELCOME.VOC
1stReader will stop the search with the first filename it
locates. If the file is found 1stReader will play the file
through your sound card. This feature lets you tie sound
files together with text files that are already displayed by
1stReader.
Page 25
Note that if the file you are displaying already includes an
extension then 1stReader strips the extension from the
filename and performs the same search. For example, if the
filename was WELCOME.TXT then 1stReader strips the ".TXT"
from the filename and begins the search.
This feature allows sysops to include .VOC files that are
automatically played whenever a mail packet from their system
is unpacked, or a bulletin is displayed....anything!
.MME files
----------
The ".MME" file extension is used by 1stReader to link other
.VOC or .CMF files together into one sound 'stream'. A .MME
file is a text file that points to other .MID, .CMF and/or
.VOC files that are to be played in order by 1stReader. An
example of a .MME file might be:
APPLAUSE.VOC
WELCOME.VOC
STARTREK.CMF
If this file was called WELCOME.MME then when the WELCOME
file is displayed by 1stReader it will read WELCOME.MME and
then play, in order, APPLAUSE.VOC, WELCOME.VOC and
STARTREK.CMF. These three files can be located in the BBS
subdirectory, inside the \1ST\MME subdirectory or in \1ST
itself.
Page 26
Special files
-------------
1stReader has reserved filenames for special features used
throughout the reader. As always, 1stReader looks for these
files in the BBS subdirectory first, then the \1ST\MME
subdirectory and finally in the \1ST subdirectory. These
files can use the .MME, .MID, .CMF or .VOC extensions
depending upon your needs.
$$ALARM
-------
Played whenever 1stReader connects to a bulletin board system
or finishes a file transfer with the bulletin board.
$$CHKPRT
--------
This file is played whenever you attempt to print text on
your printer but your printer is not ready to print (either
not connected, not turned ON or the printer is not ONLINE).
$$EXIT
------
Played when you exit 1stReader and return to DOS.
$$H-<help_recnum>
$$HELP
-----------------
$$HELP is played after the online help facility is used AND
the user has not turned on the "Advanced Features" switch.
1stReader will look to see if $$H-<help_recnum> is on file
and if found, will play it before it plays $$HELP.
<help_recnum> is the record number for that particular
help function.
$$INTRO
-------
Played at the start of 1stReader before you arrive the
opening menu.
\1ST\BBS\<confnum>
------------------
This file lets a sysop tie a particular MME file to a
conference on their system. It is played whenever you join
<confnum> in 1stReader.
Page 27
NEWS
NEWFILES
SERVICES
LEAVING
--------
These four MME files are played after a mail packet has been
unpacked but before arriving at the "Read messages" menu.
NEWS is played if a news bulletin is in the mail packet.
NEWFILES is played if a list of new files has been included.
SERVICES is played if services were included in the mail
packet. And finally, LEAVING is played when the user
selects the "QUIT" button from the "Read messages" menu.
$$TRANS
-------
This file is played after a file transfer has been completed.
If $$TRANS.* is not on file then 1stReader will use $$ALARM
instead.
Page 28
The 1stReader Applications Program Interface (API)
--------------------------------------------------
The 1stReader API is designed to let third-party programmers
have access to the internal information used by 1stReader.
Power users will also find the API of interest. That's
because we have provided you with special functions that let
you access the API from with batch files and 1stReader
itself. These functions are:
@API(xx) Accesses the integer API entries.
"xx" can be between 0 and 275.
@API&(xx) Accesses the long integer API entries.
"xx" can be between 0 and 10.
@API$(xx) Accesses the API text entries.
"xx" can be between 0 and 165.
@SWITCH(xx) Accesses the setup switches.
"xx" can be between 1 and 36
The actual API values are listed below. It is important to
remember that 1stReader supports these (and ALL) @variable
definitions in filespecs, text entries and descriptions.
They come in VERY handy with the .CMD and .LST files.
Here is a list of the 1stReader API entries. If you have
specific questions about any of these entries please leave us
a message on our customer support system at (615) 230-8822.
1stReader Integer API table
-------------------------------------------------------------
1: Text file (1STTEXT) file handle
2: Segment address of 1STTEXT (if loaded)
3: SCREENS file handle
4: Length of the DialDir entry
5: Phone Book file handle
6: Number of screens on file
7: Screen buffer segment address
8: Current screen number
9: Reader screen buffer
10: Does a mouse exist?
11: Mouse cursor state
12: Are we in ScrnEdit?
13: Last keyboard field entered
14: The user cannot access help from this location
15: Total number of systems on file
16: Current system record number
17: Are we inside QmSetup?
18: Are we inside ShowFile?
19: Qmail Door serial number
Page 29
20: Is the user a sysop?
21: Maximum number of lines per message
22: Number of conferences on file
23: Number of login names
24: Number of active conferences
25: File handle for MESSAGES.DAT
26: Current conference number
27: Current MIDI velocity value
28: Is music enabled for this display?
29: Is this display an ANSI ART display?
30: Last conference joined
31: Number of messages in conference
32: Current message number in conference
33: Number of lines in current message
34: Is this message an ANSI message?
35: Last message number loaded
36: Current line number in message
37: File handle for the replies file
38: A DosService call was made
39: Normal message text color
40: Quoted message text color
41: Search message text color
42: Current message file buffer
43: Was a bookmark read?
44: Is this message addressed to you?
45: Message type (1=Public, 2=Private, 3=Comment,
4=Sender, 5=Group)
46: Is the message read (1=Yes, 0=No)
47: Number of mouse traps in effect
48: Number of files downloaded in TERMINAL mode
49: Are we in batch mode using /CALL or /ONLYREPS?
50: File handle for zippy file search
51: Are we in color mode?
52: How many active keywords are there in the scan?
53: Is this message a USENET message?
54: Was F10 pressed? (The action key)
55: Number of names in TWIT file
56: Reload the TWIT file?
57: Last conference joined since Zippy
58: File handle for folders
59: Are we in the initial IPL for the reader?
60: Stacked OPTION command (used when CTRL is pressed)
61: Are we currently inside QmListFile?
62: Was a packet found on startup in the work
subdirectory
63: Highest conference number
64: Last message line displayed at top in internal quoter
65: Number of messages tagged for archiving
66: If set then the message is not redisplayed
67: Number of files found in the mail packet
68: Direction of the QmScrnEdit field movement
69: File number for services.dat
70: Number of services on file
71: File handle number for the .QWK packet
Page 30
72: Number of new bulletins found
73: Packet number selected
74: Set for QmListConf
75: Display this message in ANSI
76: Button pressed in MouseRange()
77: Mouse button selected in MouseRange()
78: Number of messages in this packet
79: Have we initialized the modem?
80: Force carrier on modem?
81: The comm ABORT switch
82: Recycle to next call in queue
83: Echo received characters from comm port on screen?
84: Number of LOOK variables defined
85: Timeout value for comm routines
86: Is autoZmodem downloads enabled?
87: Are we in terminal mode?
88: Reload the current message?
89: Are we in the terminal program
90: Buffer position for comm routines
91: Was JH called?
92: IRQ number
93: Base address
94: Reading without a packet on file?
95: Flow control parameter
96: Is the comm port open?
97: FIFO buffer size
98: Are we now reading a packet?
99: Are we inside a script?
100: Is this message routed from PostLink?
101: Is this message routed from Usenet?
102: Is AutoExit in terminal enabled?
103: Are we inside the DOS SHELL (F6) handler?
104: Was /QWK: used?
105: Was /REP: used?
106: Are we inside the function menu routine?
107: Maximum number of messages per conference
108: Use "UN:" on this message?
109: Was this mail packet mangled by EZ-Reader?
110: Mixed case entry flag
111: Fido style taglines flag
112: Have mail headers been swapped out?
113: Current field number in screen
114: Are we inside the editor subroutine?
115: CONTROLTYPE = ADD found in DOOR.ID
116: Should ADD/DROP buttons be displayed?
117: Are we inside the DOOR setup routine?
118: Strip @X codes?
119: International date format (0=USA, 1=EUROPE, 2=JAPAN)
120: Is a message loaded?
121: Are we inside the QmListConfs routine?
122: Is Doorway mode turned on?
123: Was doorway mode turned on while executing a script?
124: Maximum number of lines in a reply
125: Were services included in this packet?
Page 31
126: Was KEYBOARD.$$$ read?
127: HELP.DAT handle
128: Help record file
129: If set then use 4DOS BTM files
130: Maximum possible number of messages allowed
131: Was HELP just called?
132: Last archive packet used
133: Number of Replace$() variables defined
134: Archiver used to unpack mail packet
135: Are we ordering 1stReader?
136: Was the last unpack operation successful?
137: Stop the pause in QmFileDisplay?
138: Size of 16550 FIFO stack (modified by 1st)
139: Are we inside help?
140: Is the user a Qmail Door owner?
141: Are we inside the internal editor?
142: Number of times TIMEOUT was hit in script
143: Number of times for TIMEOUT to hit before ABORTing
script
144: Capture buffer file number
145: Reload the message display screen?
146: Current serial port
147: Connect flag from $$DIAL.SCR
148: Is this a Blue Wave packet?
149: Is the user "NEW USER"?
150: 0=TERMINAL, 1=CALL, 2=MAIL, 3=REPLY
151: Reserved
152: Reserved
153: Reserved
154: Is /MLIST used on the command line?
155: Fido tags turned on by @FIDO@?
156: Do not use $$DIAL.SCR
157: Reset the line input routine?
158: Use the disability switch?
159: Is DesqView active?
160: Screen buffer address
161: Did the last ANSI string contain a MUSIC string?
162: Number of lines in display for ANSIART message
163: Number of lines in display for ANSI file display
164: No Blink active?
165: Top of screen to protect in QmSetWindow
166: Left margin of screen to protect in QmSetWindow
167: Bottom of screen to protect in QmSetWindow
168: Right margin of screen to protect in QmSetWindow
169: Maximum number of lines in screen
170: Is this message larger than 200 lines?
171: Was this message already displayed as ANSI?
172: Last ROW used in virtual keyboard
173: Last COLUMN used in virtual keyboard
174: Can .VOC files be played by this system?
175: Can .MID and .CMF files be played by this system?
176: Abort all MME files in queue?
177: Always display messages in ANSI
178: Number of messages to be stored in EMS
Page 32
179: EMS handle for messages stored in array
180: Size of bookmark segment
181: Bookmark segment address
182: Noblink ANSI message
183: Number of lines in the display
184: Number of lines to protect in message display
185: Number of conferences in the first data segment
186: Number of conferences in the second data segment
187: Was ESC pressed to terminate the list of msgs
188: EMS handle for QmText (if loaded high)
189: Are we reading from the database?
190: Has we asked if this message should be displayed as
ANSI
191: Display mail packet names in packet screen.
192: Tearline in a message
193: Redial attempts
194: If set then on loss of carrier abort a redial.
195: Alias number used when saving a message
196: If true then NEWFILES.EXE is supported
197: Is the /SILENT switch used
198: Maximum length of UCode$()
199: If ON then do not act on $<command> in ANSI display
200: Draw the dialing box in terminal mode?
201: Are we in a DOS shell?
202: Number of ESC sequences in the current msg
203: DOS success flag
204: If set then do not perform a hangup during redials
205: Number of script files in the current CHAIN
206: Reserved
207: Reserved
208: If true we are calling for MAIL
209: Maximum number of taglines allowed
210: If TRUE then initialize API$(130-134)
211: If /SHOWDEL switch is turned ON
212: Number of messages to move forward to get to the next
message
213: Are we in the QmComm module?
214: Are we in the file manager module?
215: Are we editing a big file?
216: Is DEBUG turned on?
217: Is local ECHO turned on?
218: Sound Blaster support using CTVDSK?
219: Sound Blaster support using CMFDRV?
220: Dialing prefix number to use
221: If set then scan for MME files in subdirs
222: Were MME files found in API$(5)
223: Were MME files found in API$(28)
224: Were MME files found in API$(111)
225: Were MME files found in BBS directory?
226: File handle number for SERIAL.DBG
227: True if /ONLYREPS was used
228: Are we managing taglines?
229: Are we inside QmSetup()?
Page 33
230: Number of milliseconds to pause during an ANSI
position
231: Have we already tried to init the Sound Blaster?
232: Have we loaded a font?
233: Last interrupt number serviced
234: Returns the value of AL after an interrupt
235: Address of the API$() data segment
236: Address of the API$() data offset
237: Address of the API&() data segment
238: Address of the API&() data offset
239: Address of the CFG data segment
240: Address of the CFG data offset
241: Address of the DIALDIR data segment
242: Address of the DIALDIR data offset
243: Address of the Index() data segment
244: Address of the Index() data offset
245: Address of the CONF data segment
246: Address of the CONF data offset
247: Register pair AX returned after the interrupt
248: Register pair BX returned after the interrupt
249: Register pair CX returned after the interrupt
250: Register pair DX returned after the interrupt
251: Register pair SI returned after the interrupt
252: Register pair DI returned after the interrupt
253: Register pair DS returned after the interrupt
254: Register pair ES returned after the interrupt
255: Register pair SS returned after the interrupt
256: Register pair SP returned after the interrupt
257: Register Flags returned after the interrupt
258: Maximum number of lines per message
259: EMS handle for lines pointers stored in array
260: Scrollback segment address
261: Scrollback buffer size
262: Pointer into scrollback buffer
263: True if we are calling to order keyfile
264: Disable Desqview time slice
265: Modem redial delay
266: Enclosed file was found in the current message
1stReader Long Integer API table
-------------------------------------------------------------
0: Serial number
1: Total number of records in MESSAGES.DAT
2: Total number of records in REPLY file
3: Beginning position of the bookmark inside the .QWK
4: Current baud rate
5: Last time a character was received in comm channel
6: Current message record number in MESSAGES.DAT
7: Total number of records in FOLDER
8: Highest message number in the base
9: CONNECT baud rate
Page 34
1stReader String API table
-------------------------------------------------------------
1: Path to the packets subdirectory
2: Path to the download files subdirectory
3: Path to the programs files subdirectory
4: Path to the opening subdirectory
5: Path to the system subdirectory
6: Path to the reply packets subdirectory
7: Mail packet extension (Q*)
8: Reply packet extension (REP)
9: Mail packet filespec (No path)
10: Name of PACKET ID
11: Name of BBS
12: Mail packet name
13: Reply packet name
14: Path to BBS subdirectory
15: Path to the work subdirectory
16: Path to the replies subdirectory
17: Path to the services subdirectory
18: Path to the folders subdirectory
19: Last import file subdirectory
20: TWIT list filespec
21: Last folder filespec (no .FOL extension)
22: Current conference name
23: Name of the SERVICES.LST file
24: Last conference name
25: Release date
26: Suffix of the ID keyfile
27: Path to the .SET file
28: Path to the startup subdirectory
29: Path to the SYSTEM files subdirectory
30: Name of system
31: Telephone number
32: Sysop's name
33: Door ID
34: Date of packet
35: Time of packet
36: User's name
37: Second scan name
38: Third scan name
39: Name of system's phone book
40: Welcome filespec
41: BBS news filespec
42: Goodbye filespec
43: Quote name
44: Name of the bookmark file
45: CTRL sequences for OPTIONS
46: ALT translation string
47: Telephone number being dialed
48: Mail packet transfer protocol letter (defaults to
Zmodem)
49: Quote character
50: Full path to MESSAGES.DAT
51: Full path to the REPLY .MSG file
Page 35
52: Scan entry #1
53: Scan entry #2
54: Scan entry #3
55: Scan entry #4
56: PostLink routing site
57: Last directory viewed in reader menu
58: Path to the subdirectory being viewed in program
manager
59: Filespec currently selected in the program manager
60: Usenet Path
61: From
62: Newsgroups
63: Subject
64: Message ID
65: Date
66: References
67: Sender
68: Organization
69: Domain
70: Reply-To
71: To
72: Last color change issued by ANSI
73: Name of the USENET.ID file
74: User name in upper/lower case
75: User name in Usenet format
76: Comm port base address in HEX
77: String passed to program from DOS shell
78: String value present when QmEditor executed
79: Control name for door ADD/DROP
80: Name of the service file (no path or extension)
81: Last DOS command selected in QmMenu
82: Conference name (dots removed)
83: Current contents of the keyboard input buffer
84: Current conference name
85: Message number
86: Date
87: Time
88: Status
89: To
90: From
91: Subject
92: Refer
93: Reader
94: Serial number
95: Tagline
96: Actual PCB message header
97: Last color saved by @X00
98: Last highlight ANSI switch used
99: Fido Address (if any)
100: Current conference number
101: File request filespec
102: User's first name
103: Doorway ON string
104: Doorway OFF string
Page 36
105: PC Pursuit access number
106: PC Pursuit user ID
107: PC Pursuit password
108: PC Pursuit city ID
109: List of systems to call using /CALL or tagging
110: Linked script file
111: MME subdirectory
112: Log capture filespec
113: Name of reader for OEMS
114: Tagline entry
115: Date seperator
116: Temporary help file to pass
117: Path to the database subdirectory
118: Start time to call systems (using /CALL:)
119: Data to be replaced with "Ω" in the DOS shell
120: System IDs called in batch mode
121: Serial number of reader
122: Attached filename
123: Original script name
124: Last telephone number dialed
125: Swap filespec
126: Script file to execute BEFORE dialing phone number
127: Script file to execute AFTER dialing phone number
128: Modem dialing prefix #1
129: Attached filename on PCBoard
130: Full name of the $$1ST.LST file
131: Full name of the $$1ST.CMD file
132: Full name of the $$pp.LST file
133: Full name of the $$pp.CMD file
134: Name of conference .LST file
135: Name of conference .CMD file
136: Name of the .CFG file
137: Modem dialing prefix #2
138: Font filename
139: Command line used to start 1stReader
140: Last DOS command executed by 1stReader
141: Used if message is a return receipt from PCBoard
Page 37
@Variables supported by 1stReader
---------------------------------
This is a list of all @variables supported by 1stReader. You
may use these variables in any file, script, .CMD, or .LST
file.
Variable Description
------------------- ---------------------------------
@CLREOL@ Clears display to the end of line
@DATE@ Current system date
@SYSDATE@ Current system date
@TIME@ Current system time
@SYSTIME@ Current system time
@TO@ Message "TO" field
@FROM@ Message "FROM" field
@SUBJECT@ Message "SUBJECT" field
@GOODNAME@ Your name in upper/lower case
@USENETNAME@ Your name in Usenet "." format
@EDIT@ DOS editor command
@LIST@ DOS list command
@ORIGINAL@ Original message filespec
@REPLY@ Reply message filespec
@BBSID@ Qmail Door packet ID
@MEMORY@ Free memory available in 1st
@VERSION@ 1stReader release edition
@PHONE@ Telephone of the BBS
@CONF@ Current conference name
@CONF2@ Current conference (underscored)
@FILEDIR@ files subdirectory
@FIRST@ First name (from BBS login field)
@COMPORT@ Serial port entry in SETUP/COMM
@DAY@ Today's name (Mon, Tue, etc.)
@POS:nn@ Tabs to column "nn" (one per line
only)
@API$(xxx) This variable reads the 1stReader
API string table and is replaced
with the current value.
@API(xxx) This variable reads the 1stReader
API integer table and is replaced
with the current value.
@API&(xxx) This variable reads the 1stReader
API long integer table and is
replaced with the current value.
Page 38
@SWITCH(xx) This variable reads the 1stReader
switches table. If the switch is
turned ON then a "-1" is
returned. Otherwise, a "0" is
returned. See the "SWITCH"
script function for a complete
list of switch numbers.
@REPLACE(xx) At times 1stReader will pass
arguments to batch files using
'%1', '%2' or '%3'. You can
call these replacement variables
directly if you wish.
These @variables are available if you are reading a message
from a 'Usenet' conference:
@U-PATH@ 'Path' line in message
@U-FROM@ 'From' line in message
@U-NEWSGROUPS@ 'Newsgroups' line in message
@U-SUBJECT@ 'Subject' line in message
@U-MESSAGE-ID@ 'Message-ID' line in message
@U-DATE@ 'Date' line in message
@U-REFERENCES@ 'References' line in message
@U-SENDER@ 'Sender' line in message
@U-ORGANIZATION@ 'Organization' line in message
@U-DOMAIN@ 'Domain' line in message
@U-REPLY-TO@ 'Reply-To' line in message
1stReader will also substitute any DOS environment variables
by enclosing them in "%" characters. For example, %PATH%
would be replaced with the DOS path from your environment.
Page 39
1stReader script language
-------------------------
Script commands are in FULL CAPITAL letters. Required values
are enclosed in <arrows> and optional values are enclosed in
[brackets]. Of course, do not include these characters in
the actual command.
Sometimes command parameters will be enclosed by quotation
marks. If present in the command description then these
quotation marks are required in the actual command line.
@API$(xxx)="value" Type: command
@API&(xxx)=value
@API(xxx)=value
@SWITCH(xxx)=value
These commands let the scripts modify the 1stReader API. See
the API definition list to determine the correct value for
"xxx" for each variable.
ABORT <value> Type: command
The ABORT command works with the TIMEOUT command to determine
how many carriage returns must be sent (without a response
back from the BBS) before 1stReader declares the script to be
'locked up'. If the number of carriage returns transmitted
exceed <value> then the script is aborted by 1stReader.
API <value> Type: function
The API function reads the integer API table for entry
<value>. Some API values are flags that can be tested for ON
or OFF conditions. This function lets you conduct those
tests.
AUTOEXIT <on|off> Type: command
The AUTOEXIT command controls how 1stReader will exit out of
the TERMINAL mode. If AUTOEXIT ON is set then if carrier is
lost while the user is in terminal mode, 1stReader will exit
the script. AUTOEXIT OFF causes 1stReader to stay in the
terminal mode until the user presses ALT+X to exit.
Page 40
BREAK [value] Type: command
Sends a TRUE break signal to the host computer. [value] is
the number of 18ths of a second to hold the break signal.
If [value] is omitted then 1stReader uses 18 as a default.
CALL <script file> [label] Type: command
The CALL script command lets you call another script file
and then when the script exits control returns back to the
original script that was running. This command helps
modularize script functions without having a maze of GOTOs
to get back to the original script.
You can specify a label to start execution of <script file>
by adding it to the CALL command.
CAPTURE <on|off> Type: command
The CAPTURE command will open a file named <BBSID>.CAP in the
1stReader system subdirectory. This file will capture the
screens displayed by 1stReader so you can review it later.
If the capture file is left open when a script terminates
then 1stReader will close the capture file automatically.
CHECKTIME(hh:mm,hh:mm) Type: function
CHECKTIME accepts two times (in military format). The first
"hh:mm" represents the START time to check and the last
"hh:mm" represents the END time to check. If the current
time IS BETWEEN these two values then this function is set to
TRUE. Otherwise, the function returns FALSE.
CLS Type: command
The CLS command will clear the screen and set the cursor to
the top of the screen.
COMMENT "string" Type: command
This command lets you display a comment on the screen in the
area setup below the LOCKLINE value.
COUNT <qwk|rep> Type: command
The COUNT command increments the number of QWK mail packets
received and the number of REP mail packets uploaded to the
bulletin board system.
Page 41
DEBUG Type: function
The DEBUG function lets you test to see if DEBUG SCRIPTS
(switch #18) has been turned on by the user. You could use
the SWITCH function to test for this condition but the DEBUG
function provides better script readability.
DISCONNECT <baud rate> Type: command
Some systems you may call have high speed and low speed
lines. You might try to connect to a node capable of 38400
baud but since all high speed nodes are busy you end up
connect to a 2400 baud node. Obviously, if you are using
1stReader in the middle of the night on automatic you do not
want to make a full mail run at the lower speed.
The DISCONNECT <baud rate> command tells 1stReader that if
you connect at speeds lower than <baud rate> to disconnect
from the system. Example:
IF DISCONNECT 9600 THEN GOTO LOGOFF
If you connected to the system at less than 9600 baud then
control is sent to the LOGOFF label.
DOWNLOAD <filespec> Type: command
The DOWNLOAD command will download <filespec> using the
Zmodem file transfer protocol.
EDIT <filespec> Type: command
The EDIT command lets you edit <filespec> from inside a
script. If <filespec> does not exist it will be created for
you.
EXIT Type: command
The EXIT command will immediately disconnect the BBS and exit
the script. You should use it if you wish to exit a script
without waiting for the BBS to disconnect from you.
Page 42
FLAG <filespec> <byte_num> Type: function
This script function is intended to use <filespec> as a set
of external 'semaphores' for scripts. You can use this
function to check the value of <byte_num> in <filespec>. If
the value of <byte num> is ZERO then FLAG returns a FALSE
condition, otherwise it returns TRUE. You can use this
function in a IF THEN statement to branch depending if a
semaphore is turned on or not.
FOUND=<value> Type: function
The FOUND function returns which prompt string was found
using a WAITFOR command. If a WAITFOR command uses multiple
target prompts (example: WAITFOR "Yes|No") the FOUND=
function will return a value of "1" if "Yes" was found or "2"
if "No" was found.
GOSUB <label> Type: command
The GOSUB command lets you call a subroutine in your script
that is located at <label>. You can nest up to 20 GOSUB
calls in one script.
GOTO <label> Type: command
The GOTO command transfers flow of the script to <label>. A
label always starts with a colon and is one word long on a
line by itself. Up to 100 labels may be defined in a script.
HANGUP Type: command
The HANGUP command will immediately terminate the connection
to the remote BBS.
HELP <number> Type: command
The HELP command displays the online help available from
inside 1stReader's HELP files. See the list of HELP
functions for more information.
Page 43
IF ...... Type: statement
You may use the IF statement to test for various conditions
and execute a command based on the results. The syntax of
the IF statement is:
IF <function> THEN <command>
You may use any <function> defined in the script language and
combine it with any <command> as the object of the IF
statement.
1stReader also provides for a NOT modifier so you can test if
a particular function is not true. The NOT statement must
come before the <function>. The syntax of the IF statement
using a NOT modifier is:
IF NOT <function> <command>
KEYSTROKE=<value> Type: function
This function returns the ASCII value of the keystroke given
to the last PAUSE command. If a lower case character was
pressed then 1stReader automatically converts it to upper
case for you.
Example:
PAUSE
IF KEYSTROKE=13 .... ' Enter was pressed
IF KEYSTROKE=27 .... ' ESC key was pressed
IF KEYSTROKE=32 .... ' Space bar pressed
KILL <filespec> Type: command
The KILL command will erase <filespec> from the drive.
LIST <filespec> Type: command
The LIST command will display a text file using the internal
file lister. The difference between the SHOW and LIST
commands is that the SHOW command loads the text into memory
and displays it using the help screen while LIST will display
any size file using the internal list routines.
LOCATE <row>,<column> Type: command
The LOCATE command locates the cursor at <row>,<column> on
the screen. You can use this command to position the cursor
just before a PRINT statement to position text on the screen.
Page 44
LOCKLINE <row> <attribute> Type: command
The LOCKLINE command lets you allocate a section of the
screen for COMMENTs from the script file. <row> is the row
number on the screen (rows 1 through 24) to "lock" so
comments may be printed below it. In other words, <row> is
the last row that information received from the BBS is
displayed. Immediately after <row> a line is drawn by
1stReader. <attribute> is the color attribute value that is
used to paint the remaining rows underneath the solid line.
LOOKFOR "prompt string" "transmit string" Type: command
The LOOKFOR command is used to scan incoming data for "prompt
string" and if found, transmit "transmit string". If you
wish to remove a LOOKFOR command that is already in place use
the syntax LOOKFOR "prompt string" "". The null string in
place of the "transmit string" tells 1stReader to remove the
LOOKFOR command. Remember, the "prompt string" must match
the original string. Up to 10 LOOKFORs may be active at any
one time.
You can also use the LOOKFOR statement "@HANGUP@" to have
a script automatically terminated if a particular string
is found. Example: LOOKFOR "search string" "@HANGUP@"
MME <filespec> Type: command
The MME command lets your scripts play .VOC, .CMF or .MME
files through a Sound Blaster (or compatible) card. The
Multimedia switch must be turned on in SETUP/SWITCHES in
order to play <filespec>.
NEWFILES <ON|OFF> Type: command
The NEWFILES command tells 1stReader that the bulletin board
system can use the NEWFILES.EXE program to display the list
of new files. Otherwise, new files lists are displayed
internally by the reader.
Page 45
NEW_PASSWORD Type: command
NEW_PASSWORD will generate a new password your user account
that is eight characters of random letters. This command
is used together with the SET_PASSWORD command to create a
new password your bulletin board login account. Some systems
(PCBoard 15.0 for example) can force you to change your
password at different times. These two script commands let
1stReader changes your password for you automatically.
The new password is assigned to the @PASSWORD@ variable.
PAUSE [seconds] Type: command
The PAUSE command will pause execution of the script for
[seconds]. If you do not use a [seconds] argument then the
script will pause until you press any key.
PLAY "string" Type: command
This command will play the ANSI music enclosed in "string"
through the PC's internal speaker (if the MUSIC switch has
been turned ON).
PROMPT <text> Type: command
This script command will display a boxed prompt for two
seconds in the middle of the screen containing <text>.
REQ_FILE <filespec> <conference> Type: command
The REQ_FILE command will let a script add a file request to
the current file request list. <filespec> is the name of
the file to download and <conference> is the conference
number where the file can be found.
REQ_SETFILE <filespec> Type: command
This command tells 1stReader to read <filespec> to find
files requested from the NEWFILES.EXE program.
REQ_NEXT Type: command
REQ_NEXT reads <filespec> (used by REQ_SETFILE) to find the
next file request in <filespec>. You can find out if a file
was found by REQ_NEXT by using the REQ_DONE function.
Page 46
REQ_DONE Type: function
This function is set to TRUE if 1stReader cannot locate a
file request in the file set by REQ_SETFILE. Use this
function in a IF-THEN statement to stop reading the file.
REQ_CONF Type: function
This function is set to the conference number that contains
the next file to download. If REQ_CONF is set to ZERO then
the next file is located in the current subdirectory.
REQ_SET Type: command
The REQ_SET command will set a flag in <filespec> that tells
1stReader that @REQ_FILE@ has been downloaded successfully.
REPLIES Type: function
The REPLIES function will check to see if a @BBSID@.REP file
exists in the packets subdirectory. Use this function with
an IF statement to determine if replies are on file and
should be uploaded.
RETURN [label] Type: command
The RETURN command returns execution of the 1stReader script
to the next command after the calling GOSUB command. If you
include the optional [label] then execution resumes at the
statement following the label.
RUN <script filespec> [label] Type: command
The RUN command lets you load a new script into 1stReader.
If you include the optional [label] then execution will begin
at the label.
SET_FLAG <filespec> <byte_num> <ON|OFF> Type: command
This script command compliments the FLAG function described
earlier, except this command will either turn the byte
<byte_num> located in <filespec> to ZERO (for OFF) or to ONE
(for ON). You can use this command to set a flag in an
external file so scripts can branch depending on the value
of <byte_num>.
Page 47
SET_PASSWORD Type: command
This command is to be used along with the NEW_PASSWORD
command to generate a new password for your login account.
The SET_PASSWORD command writes the new password created by
the reader to your dialing directory entry. Otherwise, the
password would NOT be saved by 1stReader.
SHOW <filespec> Type: command
The SHOW command will display a short text file on the
screen. The difference between the SHOW and LIST commands is
that the SHOW command loads the text into memory and displays
it using the help screen while LIST will display any size
file using the internal list routines.
SWITCH <value> Type: function
The SWITCH function lets you query the 1stReader switch
settings. You can then use an IF statement to take action
based on the way a particular switch is set. <value>
corresponds to the following table:
Value Switch description
----- ------------------
1 Advanced features
2 Use bookmarks
3 External editor
4 Color monitor
5 Sound
6 Auto list messages
7 Sort systems
8 Random taglines
9 Music
10 MultiMedia
11 Use mouse
12 Auto position mouse
13 FIDO taglines
14 Use DTR to hangup
15 PostLink routing
16 Load 1STTEXT
17 Top of form on printer
18 Debug scripts
19 Log calls
20 Save new file lists
21 SuperShell to DISK
22 SuperShell to EMS
23 Skip messages you have read
24 Terminal alarms
25 Sort conferences
26 Large message screen
Page 48
27 Using 4DOS
28 Lock serial port
29 Auto alias
30 Show packet names
31 Trim quotes
32 Disable ANSI messages
33 Quick scan messages
34 Clear input fields
35 Ask on ANSI messages
36 Skip messages from you
Remember you may use the IF NOT condition to see if a
particular switch has been turned OFF.
TERMINAL Type: command
The TERMINAL command does not have any arguments. It will
send the user into an immediate terminal mode. To exit the
terminal mode and return to the script press ALT+X.
TERSE Type: command
This script command has no parameters...it is used to switch
PCBoard systems from the standard 'text' display mode to a
'terse' display mode. This makes it possible for 1stReader
scripts to be 'language independent' and work on all PCBoard
systems. The price you pay is that you also give up seeing
the normal text prompts and instead see only TXTnnn
prompts.
TRANSMIT "string" Type: command
The TRANSMIT command will transmit "string" to the remote
system.
TRANSMIT; "string" Type: command
This command works just like the TRANSMIT command except that
any embedded spaces are converted into semi-colons. For
example, TRANSMIT; "Mark Herring" would be converted into
"Mark;Herring". This command can be used to log into systems
that require semi-colons for a single-line login.
Page 49
TIMEOUT <seconds> Type: command
The TIMEOUT command sets the number of seconds that must pass
without receiving data from the remote system before the
reader will transmit a carriage return. This command is used
to catch situations where you might be sitting at the
"Command?" prompt on PCBoard yet the script may not catch it.
If you wish to disable the TIMEOUT completely use a value of
0 seconds.
UPLOAD <filespec> Type: command
The UPLOAD command will upload <filespec> using the Zmodem
file transfer protocol.
WAITFOR "prompt string" [seconds] Type: command
The WAITFOR command scans incoming text for "prompt string".
When "prompt string" has been found execution of the script
continues. [seconds] is an optional value that can be added
to the command so that WAITFOR only waits for [seconds] for
"prompt string" to be found. If [seconds] pass with or
without finding "prompt string" execution of the script
continues.
You can scan for more than one value by separating the values
using "|" bar characters. For example, WAITFOR "Yes|No"
would wait for either "Yes" or "No" to be received. You can
later test which value was received by using the FOUND=
function.
WEEKDAY Type: function
The WEEKDAY function returns the day of the week in numeric
form. Sunday=1, Monday=2, Tuesday=3, Wednesday=4,
Thursday=5, Friday=6, Saturday=7. You can use this function
with the IF function to find out which day of the week today
falls upon.
Page 50
Special @variables
1stReader maintains special @variables that can be used by
scripts. Here is a list of variables supported:
@BBSNAME@ The name of the BBS.
@USER@ The name of the LOGIN field in the
BBS record.
@PASSWORD@ The password field in the BBS
record.
@SYSTEMDIR@ Location of the 1stReader system
subdirectory.
@PACKETDIR@ Location of the mail packet
subdirectory.
@DLDIR@ Location of the file download
subdirectory.
@REPDIR@ Location of the replies
subdirectory.
@PROGDIR@ Location of the PROGRAMS
subdirectory.
@LANGAUGE@ The language version field from
the BBS record. If the language
value is set to "0" then this
variable will be set to blank.
@QMAIL@ This variable is set to the name
of the door command for the
BBS.
@COMMAND@ This variable will check to see if
a reply packet is available for
uploading. If a packet is found
then "U;D" is assigned to the
variable. Otherwise, "D" is
assigned.
@CONFERENCE@ The conference number field from
the BBS record. This value is
used to join a conference before
calling the mail door if it is to
be called from another conference.
@DATE@ Replaced with today's date.
@TIME@ Replaced with the current time.
Page 51
@GRAPHICS@ Set to "Y" if you have enabled
graphics for this BBS. Otherwise,
it is set to "N".
@FIRST@ Set to the user's FIRST name.
@REQ_FILE@ Filespec read from the file
request file set by REQ_SETFILE
command.
Special characters
------------------
1stReader interprets two special characters for values. The
first character is a carat "^". 1stReader will convert the
next character, if alphabetical, into a CONTROL sequence.
For example, "^G" will ring a bell or "^M" is a carriage
return.
You can also use "X'" to convert any hexadecimal value into a
single character. For example, "X'1B" converts into the ESC
character.
Page 52
Hints and Tips
--------------
This section contains 1stReader features and hints that do
not necessarily fit into any of the other areas discussed
earlier.
Support for .BIN and .B1N files
-------------------------------
1stReader can display .BIN files created by THEDRAW. 1st
also supports what we call ".B1N" (Bee One Enn) files. A
.B1N file contains TWO .BIN files copied together. The first
4000 bytes of the file (or the first .BIN file) is a
monochrome version of the screen display. The second
4000 bytes (or the second .BIN file) contains the color
version. You can create a .B1N file by creating two .BIN
files inside THEDRAW and then copying them together at the
DOS command prompt, like this:
COPY TEST.B1N+MONO.BIN+COLOR.BIN
1stReader displays the monochrome version of the file if the
color display switch is turned OFF. Otherwise, the color
version of the file is displayed.
1stReader will find .BIN and .B1N files when looking for
$$CALL files. The order of the search is:
.ASC
.ANS
.B1N
.BIN
The WELCOME file
----------------
When you startup 1stReader it will look for a file named
WELCOME in the system subdirectory. This can be a customized
file created by the user. WELCOME.ASC, WELCOME.ANS,
WELCOME.B1N, WELCOME.BIN and WELCOME.GIF are supported.
Page 53
Using KEYBOARD.$$$ from the internal editor
-------------------------------------------
If you shell to a program while inside 1stReader's internal
editor and KEYBOARD.$$$ is created, then KEYBOARD.$$$ is
pasted into the text at the current cursor location when
control returns to 1stReader.
This feature lets third-party developers create "Usenet
address books" so they can pass back Usenet addresses into
replies. Of course, there can be hundreds of uses for this
feature too.
Pre-Print and Post-Print strings
--------------------------------
You can add pre- and post-printing initialization strings to
1stReader by using our 1STTEXT.EXE editing program. This
program, which is available on our customer support system
(you can use our DLXTEXT.EXE program too) lets you edit the
1STTEXT file.
Record #282 is reserved for any printer initialization string
you require. Record #283 is reserved for any post-printing
string you require. If you need to send more than 78
characters to the printer you can tell 1stReader to read the
characters from a file. Use "FILE=<filespec>" in record
#282/#283 and 1stReader will read <filespec> for the strings.
Printer definition
------------------
Record #273 in 1STTEXT is used to declare the name of the
printer on your system. Currently, it defaults to "PRN" but
you can send printer output anywhere you wish by changing
record #273.
Create your OWN help files
--------------------------
You can "over-ride" the internal help screens we have
provided in 1stReader by creating your own HELP.xxx files.
"xxx" corresponds to the help record number. You can create
custom help files for a BBS by storing them in the BBS
subdirectory. Or, you can globally affect the files by
storing them in the SYSTEM subdirectory.
Page 54
1stReader is network ready
--------------------------
You can run multiple users from one copy of 1stReader kept on
a network. Or, you can let family members keep their own
setups without requiring multiple copies of 1stReader.
All you need to do is to create separate subdirectories for
each user. You could name them C:\1ST\JOHN, C:\1ST\BILL,
etc. You can even place them on separate drives if you wish.
Each user subdirectory MUST have a copy of 1ST.SET and
1ST.KEY in order to work. 1stReader will create unique files
and BBS subdirectories for each user.
In order to find the 1stReader system files, you need to use
the DOS environment variable "SET 1ST=C:\1ST\" (change this
to point to your 1stReader SYSTEM location) in your
AUTOEXEC.BAT file. This lets 1st find the files it needs to
run over a networked system. Remember, you must still
execute the program by typing C:\1ST\1ST from the DOS command
line or a batch file.
IMPORTANT NOTICE: YOU *MUST* PURCHASE MULTIPLE COPIES OF
1STREADER FOR EACH USER ON YOUR SYSTEM
IF USED IN A BUSINESS. IT IS A VIOLATION
OF OUR LICENSE AGREEMENT AND COPYRIGHTS IF
YOU ALLOW MULTIPLE USERS TO OPERATE
1STREADER USING THE SAME 1ST.KEY FILE.
Notice to families: We consider 1stReader to be 'marital
property'. Any family member who
lives under your roof may use your
copy of 1stReader.
GO.ASC, GO.ANS, GO.BIN, GO.B1N
------------------------------
In the file manager, after you select a subdirectory, if
1stReader finds any of these files in the current
subdirectory they are immediately displayed to the user.
The idea behind this feature is to allow archived programs
and "services" that are sent by some mail systems to have
their own "introduction" when used with 1stReader.
A word about services and 1stReader. Offline games are now
very easy to create using 1stReader's service capabilities.
Your game can use one of these GO display files to welcome
the user to the game. If a READ.ME file is found in the
service then that file is automatically displayed to the
user (game news or rules could be posted here). Finally, you
can provide a GO.BAT file so all the user has to do to start
Page 55
your game is to click on the "GO" button. Your game software
can then write any files that are needed to be sent back up
to the mail system by storing them inside the REP-WORK
subdirectory. The contents of this subdirectory are
compressed into the .REP mail packet and transmitted back to
the mail system.
If you are interested in creating offline games for use with
mail systems that support services and 1stReader, please give
our customer support system a call. We'll be happy to show
you everything you need.
Trivia games could be a good example of an offline game.
Automatic DOORWAY ON and DOORWAY OFF modes
------------------------------------------
If you call a bulletin board system using Doorway 2.22 from
Marshall Dudley then 1stReader can automatically switch into
and out of 'Doorway mode' while connected to the system.
Doorway 2.22 transmits codes that 1stReader watches for and
when found, turns 'Doorway mode' ON or OFF for the user.
Note: This feature requires use of Doorway 2.22 (or later).
"Header" files
--------------
1stReader supports "Header" files that can be used in your
editor whenever you enter a message. If the file
"HEADER.HDR" is found in either the BBS or SYSTEM
subdirectory, then 1stReader will read it and copy it into
the "top" of your reply. You can use any @variable you wish
in your header.
1stReader also looks for the text "∙HEADER:<name>" in a
message. If this text is found and <name>.HDR exists in
either the BBS or SYSTEM subdirectories, then 1stReader uses
this header file instead to begin your replies.
You can also have separate "Header" files for public and
private messages. 1stReader will determine which file is
used depending if you are replying to a public or private
message.
HEADER.PUB - Public messages
HEADER.PRI - Private messages
Sysops, this is a good candidate for your 1ST-TIME.ZIP files
Page 56
Auto sensing dialog boxes
-------------------------
If you have defined the dialog boxes to use the same color as
the current background, 1stReader switches to a WHITE
background in the dialog box automatically so the box will
stand out. If your background is white (and you are using
color) then light blue will be substituted.
"Ok" and "Cancel" buttons
-------------------------
If you are using a mouse then 1stReader will place these
mouse buttons inside keyboard dialog boxes. They do not show
up if you are not using a mouse.
Attention John Hancock fans!
----------------------------
1stReader always supports the famous "DOS:JH3" tagline. This
allows you to call John Hancock from inside 1stReader. If
you like to use a lot of taglines in the internal tagline
manager, picking out that single "DOS:JH3" tagline could be a
bear.
Instead, create yourself a "picklist" for use at the tagline
prompt when saving a message by arrowing into this field and
pressing ALT+F8. Use this entry for your picklist:
TITLE=Taglines
DOS:JH3
Press [F8] to call up the picklist. When you select
"DOS:JH3" from the list 1stReader will call John Hancock
automatically and pass the tagline to you. 1stReader
supports the "DOS:" command in taglines. If this string is
found then 1stReader will shell to DOS and execute the
command immediately after "DOS:".
Page 57
Specialized conference .BAT, .BTM, .CMD and .LST files
------------------------------------------------------
If you create files using these extensions, but using the
names of conferences, then these files are active when you
press [F6] (for .BAT files), [F7] (or .CMD files) or [F8] (or
.LST files).
This lets you create specific files that only work when you
have joined a particular conference.
Support for DOOR.ID
-------------------
If 1stReader finds a DOOR.ID inside the QWK mail packet and
the entry "CONTROLTYPE =" is found inside, then, when you add
or drop conferences using 1stReader, it reverts back to the
"old" method of writing one message at a time to add or drop
the conference. This method is provided for backwards
compatibility with older mail systems.
Downloading files
-----------------
If you download files from 1stReader's internal terminal
module or from your favorite terminal program, 1stReader will
automatically invoke the file manager and take you to your
download subdirectory when you exit the terminal mode.
This feature lets you manage the files you just downloaded in
the online session.
Longer signatures
-----------------
1stReader provides you with a "signature" field that will
automatically place your name on the bottom of messages you
enter in the reader.
However, you may find you need more lines in your signature
or you might like to incorporate graphics. 1stReader lets
you use "SIG=<filespec>" as a signature. This tells 1st to
look for the file <filespec> in the BBS subdirectory or in
the SYSTEM subdirectory. If found, the file is imported
automatically into your replies.
Page 58
Multiple signatures
-------------------
Sometimes having only one signature can be a limitation.
1stReader lets you have up to 100 signatures per system if
you need them. The trick is to use the Picklist system.
Instead of entering your name in the signature field use the
entry "NAMES.LST". Then, press the ALT+F8 key to create the
picklist. Here is an example:
TITLE=Signatures
Sparky,Sparky
Qmail Support,Qmail Support
Long signature,SIG=NAME1
When you save the message you'll be asked to select the
signature you wish to use. Notice the "SIG=NAME1" entry. If
you pick that entry 1stReader will use the file "NAME1" as
your signature.
Support for the "1ST" file
--------------------------
If 1stReader finds the file "1ST" inside a mail packet, it
will display this file to the user immediately after the
"Welcome" screen.
This file is provided so sysops can pass information on to
their offline mail users that might not apply to their
regular "online" users.
Automatic SuperShell
--------------------
If you have not turned SuperShell ON in Setup's "Switches"
section and you attempt to shell to DOS with less than 125k
of memory available, 1stReader will automatically invoke
SuperShell for you.
Page 59
Nonstandard serial ports
------------------------
1stReader will support nonstandard COM3 and COM4 setups as
long as they do not use the "high" interrupts. 1stReader
defaults COM3: and COM4: to use the industry standard
addresses, but you can override this by using the format:
Base Address,IRQ
"Base Address" is the base address of the port, in
hexadecimal. "IRQ" is the interrupt request line value. If
your system uses the industry standard addresses simply use
"3" or "4" in this field.
Also note that 1stReader supports the "%4" parameter in the
Zmodem upload and download commands too. This parameter is
replaced with the Base Address,IRQ value so QSZ can use the
"portx=" command line parameter.
New commands supported in DOOR.ID
---------------------------------
1stReader will use these commands if found in a DOOR.ID file
inserted into a QWK mail packet:
MIXEDCASE = YES
FIDOTAG = YES
If "MIXEDCASE = YES" is found then the user will be allowed
to address messages using upper and lower case. If the
string "FIDOTAG = YES" is found then messages left by
1stReader will automatically use Fido-compliant taglines.
You can use "Fido" taglines "on the fly" by including the
string "@FIDO@" in your replies if you wish. 1stReader
also automatically leaves Fido-compliant taglines if it finds
a valid Fidonet address in the tagline of the original
message.
If you use a Fido-compatible tearline then 1stReader will
search your tagline for any characters higher than ASCII 127
and if found, replace them with periods.
LIST is restricted
------------------
You cannot list files that end with a .COM, .EXE, .OVL, .ZIP,
.ARC, .ARJ, .LHA or .ZOO file extensions from within
1stReader.
Page 60
Robocomm-named packets supported
--------------------------------
1stReader will automatically find mail packets that have been
named using Robocomm's "nPACKET.QWK" format. "n" is the
packet number received for the bulletin board system.
QMAIL4 is assumed
-----------------
If you forget to enter the DOOR command in the bulletin
board's dialing entry then 1stReader will default to
"QMAIL4".
Three button mice users
-----------------------
If you use a three button mouse you'll find that clicking on
the middle mouse button will "ping pong" the mouse cursor
between the upper screen and mouse buttons on the bottom of
the screen. This feature works in the...
File management screen
List messages screen
Mail packets screen
Using SPACE BAR and SHIFT+ENTER
-------------------------------
1stReader supports use of the space bar as a method to move
through a mail packet. You can use nothing but the space to
read messages once you have selected the "Read" button from
the "Read messages" screen.
If you are using 1stReader on a laptop check out the
SHIFT+ENTER key combo. On laptops it can be hard finding
that PgDn key. If you hold down SHIFT while pressing the
ENTER key 1stReader will think you pressed the PgDn key.
Page 61
Protect those 'questionable' taglines
-------------------------------------
If you place a question mark as the first character in a
tagline, 1stReader will ask you to confirm use of the tagline
in a message.
This feature helps protect you from using 'questionable'
taglines you might use in personal messages but not in public
messages.
'Hotkey' your .CMD and .LST entries
-----------------------------------
You can add 'hotkey' support for your .CMD and .LST files by
placing the character "»" (ASCII 175) directly *IN FRONT* of
the character you wish to use for the hotkey entry.
1stReader will strip the "»" character from the string when
it is returned back to you.
Entry fields are accessible
---------------------------
Entry fields are accessible through the @API$(xxx) function.
All field entries are numbered starting with field #1 at the
top of your screen. The @API$(xxx) function lets you access
the first field by using @API$(201). The second field entry
is accessible by using @API$(202), etc.
This feature lets you pass field entries that are on the
current screen to a shelled application. Remember that these
functions only return the field entries for the 'current'
screen. If the current screen does not contain any field
entries, the @API$(xxx) function returns a null string.
Page 62
Sysops can use Qmail Door in DOS using 1stReader
------------------------------------------------
If you own a copy of our Qmail Door you can have 1stReader
scan for new mail and upload replies by using the $$MAIL.BAT
and $$REPLY.BAT files.
Your $$MAIL.BAT file should read:
@echo off
cls
c:
cd \pcb
PCBOARD /USERSYS;<first>;<last>;PWRD:<password>;TPA:QMAIL4
c:\pcb\qm4\qmail4 U;D;Y;G
PCBOARD /READSYS
Your $$REPLY.BAT file should read:
@echo off
cls
c:
cd \pcb
PCBOARD /USERSYS;<first>;<last>;PWRD:<password>;TPA:QMAIL4
c:\pcb\qm4\qmail4 U;G
PCBOARD /READSYS
<first> is your first name used to log into your PCBoard
system. <last> is your last name. <password> is the
password you use to log into your PCBoard system. You might
need to edit these batch files to change the location of your
PCBoard subdirectory. These batch files only work with
PCBoard 15.0.
Simply copy these batch files into the 1stReader BBS
subdirectory for your system and when you later select your
system from 1stReader's menu, you'll go through DOS to
transfer your mail packets instead of calling your system.
Control characters in .LST files and KEYBOARD.$$$
-------------------------------------------------
1stReader lets you use control characters in your picklists
and in KEYBOARD.$$$. If you would like to force a carriage
return you can use "^M" at the end of the entry.
Remember that when you use picklists and KEYBOARD.$$$ from a
keyboard entry field, the carriage return is automatically
supplied by 1stReader. This feature lets you force control
characters while in the internal editor.
Page 63
$$DIAL.SCR supported
--------------------
This script file can be used to dial a bulletin board system
in place of 1stReader's internal dialer. The idea behind
supporting this script file is to allow users to make long
distance calls using SPRINT, MCI or other long distance
carriers that require additional access codes.
Placing $$DIAL.SCR inside the SCRIPTS subdirectory will force
1stReader to use the script file everytime it calls a system,
regardless if it is long distance or not. We recommend that
you place this file inside the individual BBS system
subdirectory for better control.
Addition bulletin board systems supported
-----------------------------------------
1stReader now has the ability to use different script files
when calling bulletin board systems. This means that if you
are calling a Wildcat! system you can tell 1stReader to use
the Wildcat! scripts. By default, 1stReader uses the
PCBoard/Qmail Door script files.
Carriage returns in the modem initialization string
---------------------------------------------------
You can use the character "{" in your modem init strings to
indicate where a carriage return is to be inserted.
SERVICES.NEW
------------
Sysops can include a file named SERVICES.NEW in the QWK mail
packets and 1stReader will display it when the user selects
the 'Services' button. This file is intended to give
1stReader users an introduction to the services provided.
Page 64
Clear all entry fields with one keystroke
-----------------------------------------
Sometimes it might handy to clear out ALL of the entry fields
on a screen at one time. The ZIPPY scan screen is a good
example - you might have saved default values but this time
you want to search for totally different keywords. If you
wish to clear out all of the entry fields at one time press
the CTRL key and while holding it down also press the ESC
key. All of the entry field values will be erased.
QSZ supports 'crash-recovery'
-----------------------------
If you were downloading a file from a bulletin board system
and the download was interrupted before the transmission was
completed, you can simply request that the BBS send you the
file and 1stReader will resume the transmission where it left
off.
Note that 'crash recovery' is not supported while downloading
QWK mail packets.
Assign different dialing prefixes to telephone numbers
------------------------------------------------------
Some bulletin board systems use different 'hunt groups' where
one group requires use of dialing prefix #1 and the other
groups might require prefix #2. You can tell 1stReader which
prefix to use by using "Px nnn-nnnn" as the telephone number.
For example, "P2 555-1212" would tell 1stReader to use
dialing prefix #2 for this telephone number even if you
assigned prefix #1 to the system.
If you wish you can also tell 1stReader to execute a script
file for ONE particular number before dialing the number. To
do this you need to enter the name of the script file (.SCR
is assumed) in the phone entry field.
Example: "SCRIPT|555-1212"
This number would force 1stReader to execute "SCRIPT.SCR" (if
it exists) before dialing "555-1212" every time.
Page 65
Access interrupts from DOS command line functions
-------------------------------------------------
You can tell 1stReader to access a system interrupt instead
of a DOS command. The idea behind this feature is to support
any future TSRs that might be written to help the way
1stReader operates.
Essentially, this gives 1stReader a 'DLL' capability. For
example, a TSR could be loaded before running 1stReader that
lets the reader display a message in a totally different
manner than the method built into 1stReader now.
This is a feature that was available in our legendary 'QPro'
offline mail reader we wrote back in 1989 (but never made it
to market). We used it to add some rather interesting
features to QPro later and we wanted to incorporate the same
support for future use in 1stReader.
Here's how you do it. If the DOS command starts with "INT:"
then 1stReader knows we're going to call an interrupt instead
of shelling to DOS. You can pass register data on the
command line like this:
INT:$80 AX:$0601 BX:$0700 CX:$0101 DX:$1950
Notice that "$" before a number indicates the number is a
hexidecimal number. If the "$" is missing then the number is
a decimal value. The reader will then execute the interrupt
and return the value of register AL in API(234). Also, all
register pairs are loaded into the API so they can be tested
after execution of the interrupt.
You can also access an interrupt from any batch file by using
the command:
:1ST: INT:$80 AX:$0601 BX:$0700 CX:$0101 DX:$1950
The interrupt will execute and then the batch file can
perform any test on any of the register pairs (which are
loaded back into the API).
1STTEXT record #350 has been reserved to hold an interrupt
call that is executed immediately after loading a message.
Record #351 has been reserved to hold an interrupt call that
is executed just before a message is displayed on your
screen. #351 can be used to display a message in a totally
different manner from 1stReader. You can pass back a
keyboard scan code in the AL register to the program. If
AL=0 then the message is displayed normally. Otherwise, AL
contains the scancode and the reader uses it as if you
pressed the key in 1stReader.
Page 66
You can ONLY address interrupts $80 through $E9. You cannot
call any BIOS or DOS interrupt. Note that interrupts can
ONLY be called from CMD and batch files (or recs #350/#351 in
1STTEXT) on YOUR system.
NAPLPS support is now available
-------------------------------
1stReader can support practically *ANY* file type. To
illustrate this feature, 1stReader now supports NAPLPS files.
We've provided a NAPLPS kit on the distribution diskette
(file named NAPLPS.ZIP) that easily installs into 1stReader
and provides your system with the ability to display NAPLPS
files from the file manager and *anywhere* a file is
displayed. You can now include NAPLPS files in QWK mail
packets too!
NAPLPS is a graphics standard that was created 10 years ago.
You see it used often on cable TV systems. It lets fairly
complex graphics images be transmitted in very small files.
While they do not have the resolution offered by GIF files
they can occupy 1/10th the disk space, or even less.
You can study the NAPLPS.ZIP kit to see how we installed
NAPLPS support. It is VERY easy to add support into
1stReader for virtually any file type.
Make temporary changes to your 1stReader setup
----------------------------------------------
If you have ADVANCED FEATURES turned ON then 1stReader will
keep the changes you made 'in memory' and not reload the
original settings if you decide you do not want to
permanently save the changes.
Tagline support from the terminal section
-----------------------------------------
You can add this entry into your $$1ST.CMD file:
Manual tag,MACRO=---^M ■ Manual tagline^M
When you are in the terminal mode and press the F7 key and
select "Manual tag" from the menu, presto! You get a
tagline!
Page 67
The 'CONFIRMATION' field
------------------------
This field is used for you to enter any information the BBS
might require to confirm it is you who is calling. For
example, WildCat systems will sometimes ask you to enter your
birthday to confirm it is you. Other systems might ask for
your mother's maiden name. This field is limited to 13
characters.
1stReader also supports the #CONFIRM@ script variable. This
variable contains the information held in the confirmation
screen so it can be transmitted back to the bulletin board
system when requested.
The .COPY command
-----------------
Whenever long message replies are split up, sometimes it
might be nice to have the beginning of the message copied
into the extra messages created by 1stReader. For example,
if your long message contains a Usenet address header, it
would be nice to have 1stReader automatically copy the header
into the extra messages it chops up for you.
Place ".COPY" on a line by itself in your reply and 1stReader
will copy any text above it into the 'split' messages
automatically. The actual ".COPY" does not get saved with
your reply, so if you later re-edit the message, you must add
it back in yourself. A must-have for heavy Usenet users!!!
NOTE! You may copy only up to 25 lines of your message.
1stReader automatically aborts a script...
------------------------------------------
If you are dialing a system and get three 'Call Failed'
messages in a row without a 'Busy' being encountered, then
1stReader aborts calling the bulletin board system figuring
that it is not answering.
Picklist notices
----------------
1stReader will only display the "F8 = Picklist" if you are in
novice mode. It takes some disk accessing to figure out if a
picklist exists and we reasoned that if you're an expert, you
know where the picklists are anyhow.
Page 68
Scroll quickly through large messages
-------------------------------------
You can scroll 100 lines at a time (both up and down) within
one message by holding down the CTRL key at the same time you
press PgUp or PgDn.
Restricting some .CMD functions
-------------------------------
You can add the term <BBS> into any CMD command file and if
you have not selected a BBS yet from the opening menu,
1stReader will not display the command in the command menu.
Example: View capture file,#API$(28)#API$(10).CAP <BBS>
This entry means that if you haven't selected a BBS yet then
this command will not be displayed in the command menu. You
can also use the term <ADV> in your CMD files. If the user
has not turned on the "Advanced Features" switch then any
commands that include <ADV> will not be displayed in the
menu.
Locate a file inside your system's PATH statement
-------------------------------------------------
1stReader supports the "<PATH>" variable in filespecs. This
variable tells 1stReader to search the system's PATH variable
until it locates the file.
Example: "<PATH>COMMAND.COM"
This entry would tell 1stReader to search all subdirectories
in the "PATH" DOS environment variable until COMMAND.COM was
found. 1stReader then sets the full filespec to this name.
(C:\COMMAND.COM)
1st moves files automatically into the BBS subdirectory
-------------------------------------------------------
1stReader moves the WELCOME, BBS news and GOODBYE screens
into the BBS subdirectories. This lets offline mail systems
only send these files out when they are updated. This means
a BBS does not need to send a WELCOME.GIF with every mail
packet downloaded from a mail system. The file is
transferred once and as long as it is not updated by the
sysop, it never needs to be sent again.
Page 69
Disconnect immediately after an upload or download
--------------------------------------------------
1stReader supports the CTRL+PGUP and CTRL+PGDN keystrokes
while in the terminal mode. These keystrokes work just like
PGUP and PGDN do (upload or download a file) but when you
hold down the CTRL key at the same time it tells 1stReader to
hangup the connection after returning from QSZ.
How many times have you started a long file transfer to a
bulletin board system and didn't want to have to wait for the
transfer to be over in order to disconnect from the system?
Just use this feature and after the file transfer is finished
you will automatically be disconnected from the system.
Modify the 1stReader API after a DOS shell
------------------------------------------
You could always read the 1stReader API from a DOS call or
use the @variables to display contents of the API. Now you
can also update the API in a DOS shell by creating a file
named API-NEW.$$$. This file contains one entry per line,
like this:
@API$(nnn)="xxxxxxxxxxx" ' Strings
@API&(nnn)=xxxx ' Long integer
@API(nnn)=xxxx ' Integer
1stReader also adds support for the @PASS(nn) variable as
well. The @PASS variables are setup to let 3rd party
programmers pass info from one application to another through
the 1stReader API itself. Up to 20 variables are allocated
for use.
Usenet message headers
----------------------
1stReader will display up to 50 characters of the FROM and
SUBJECT fields from a Usenet message header. If the fields
are longer than 50 characters you can scroll the headers left
or right with the message text.
1stReader now automatically detects a Usenet sourced message
from any gateway (as long as a valid "Message-Id" field was
found) and will use USENET.HDR in any new message or reply
you enter automatically.
Page 70
Alias signatures
----------------
If you do not use an alias name in your replies then API(195)
is always set to "1". It can be set to "2" if the second
alias entry was used to save the message or "3" if the third
was used.
You can use this variable in your signature filespec so you
can have 1stReader point to different signatures based on the
alias entry used to save the message. For example:
SIG=NAME.#API(195)
would let you use "NAME.1" for your normal signature,
"NAME.2" for alias #2's signature and "NAME.3" for alias #3's
signature.
The virtual keyboard
--------------------
If you click a mouse button and the mouse is positioned in
the upper left corner of the screen, the virtual keyboard
will appear. This was done to help disabled users with one
finger select the virtual keyboard. You can also access the
virtual keyboard by pressing the LEFT and RIGHT mouse buttons
at the SAME time.
The EXTRA FEATURE button
------------------------
1stReader supports the $$EXTRA.CMD command menu. It would be
nice to offer sysops a way to add extra commands to the
reader to help further its functions. While pressing F7 is
always available, novices might not know about it. So an
"Extra features" mouse button has been added to the "Read
Messages" menu.
If you click on this button 1stReader will look for the
$$EXTRA.CMD command menu file (which is designed just like
any other command menu file). 1stReader will look in the BBS
subdirectory first for the file, and if not found, 1st will
look in the \1ST subdirectory. If $$EXTRA.CMD is not found
then $$1ST.CMD is used instead.
Using the additional add-in features found in 1stReader you
can add just about anything to the system now. New features
can look like they are an integrated part of 1stReader.
Page 71
Display files directly from a .CMD file
---------------------------------------
1stReader supports the "DISPLAY=<filespec>" statement in .CMD
menu files. If you use this command in place of a DOS
command then 1stReader will display <filespec> on your screen
and wait for you to press any key to continue. This feature
supports .ASC, .ASC, .BIN, .B1N and .GIF files. This feature
is ideal if you wish to add a 'boss screen' to 1stReader.
'$<macro>' now available in ANSI files and messages
---------------------------------------------------
1stReader can now use the following commands from inside text
files or messages to do the following commands. Use only one
command per line.
$BLINK ON/OFF $BLINK OFF will let 1stReader use
high intensity backgrounds in ANSI
messages. $BLINK ON turns this
capability off and turns blinking
back on.
$MUSIC ON/OFF Turns music ON or OFF. Note that
this switch DOS NOT change the switch
in SETUP that controls ANSI music.
That switch MUST be turned on for
these commands to work. These
commands reset the internal ANSI
emulator's music flag so if the user
pressed ESC to turn music off the
file can reset the switch, or turn it
off.
$TOP xx These commands set the top, bottom,
$BOTTOM xx left and right margins for ANSI
$LEFT xx screens. Note that you must not
$RIGHT xx exceed the margins for physical
screen on your system.
$LSET nn <text> These commands will take <text> and
$RSET nn <text> set itinto a blank string that is
$CENTER nn <text> "nn" characters long. $LSET will set
<string> to the left side of the
blank string. $RSET sets <string> to
the right side of the blank string.
$CENTER will center <string> into the
blank string.
$LOCATE row,col Positions the cursor to row,col on
the screen.
Page 72
$GIF <filespec> Displays a GIF file.
$NAP <filespec> Displays a NAPLPS file (if NAPLPS is
installed).
$MME <filespec> Plays a .MME, .VOC or .CMF file
through your sound card (if
multimedia is turned ON).
Sensing color attributes
------------------------
1stReader support the "@x??" color code. If "??" is used
then 1stReader uses the current color attribute on the screen
at the point where the text is going to be displayed.
The NEWS.LST file
-----------------
After displaying the BBS news, 1stReader will look for this
file and read it if found. The file contains other filenames
that should be displayed to the user. It can also contain
DOS commands if the entries begin with the string "DOS:".
This file works well for new user setups - the sysop can even
include programs that give the user a guided tour of their
system automatically.
The ATTACHED.LST file
---------------------
1stReader will look for an ATTACHED.LST file inside a QWK
mail packet and moves the attached files from the WORK area
into the DOWNLOADS subdirectory.
Save some disk space
--------------------
If you wish to save 124,504 bytes of disk space you can
delete the 1ST.B&W file if you always have the "Color
monitor" switch turned ON. If you always use monochrome
screens then you can delete 1ST.CLR instead.
Page 73
The INSTALL module
------------------
The 1stReader install program (INSTALL.EXE) is much more than
just a simple installation program. It has its own 90
command script langague that lets you program interactive
presentations, menus and all sorts of applications.
Click on the "1stTutor" button from the opening menu to see a
demonstration of INSTALL's capabilities. See "INSTALL.DOC"
for a complete list of commands supported.
Creating offline help for bulletin board systems
------------------------------------------------
1stReader can access help for a bulletin board system while
the user is in the terminal mode.
If the user presses the [F10] key from the keyboard then the
reader searches for the file <name>.INS or <name>.HLP
(<name> is the name of the script used to call the bulletin
board system). If <name>.INS is located then 1stReader
shells to the INSTALL program to run the help file.
Otherwise, <name>.HLP is displayed from within 1stReader.
Sysops can create their own custom HELP files by copying them
into their .BBS files. 1stReader will automatically install
these files when reading the .BBS files.
Page 74